{"openapi":"3.0.0","paths":{"/api/health":{"get":{"description":"Returns `200` when the API and every dependency it needs are reachable, and `503` when any check fails — the failing dependency is named under `error`. Intended as a container liveness/readiness probe, so it is unauthenticated, cheap, and excluded from request logging.","operationId":"check","parameters":[],"responses":{"200":{"description":"The Health Check is successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}},"503":{"description":"At least one dependency is unreachable. The failing check is named under `error`, and the orchestrator should stop routing traffic to this instance. Note this does NOT use the standard error envelope: the response is the health report itself.\n\nThe Health Check is not successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"error"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"},"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}}},"summary":"Report service and dependency health","tags":["Health"]}},"/api/auth/login":{"post":{"description":"Authenticates with email and password. A session is scoped to one organization: accounts belonging to a single organization are scoped automatically, while accounts belonging to several must supply `organizationId` — omitting it returns `400` listing the options.\n\nEvery authentication failure returns the same `401`, whether the address is unknown, the password is wrong, or the account is deactivated. This is deliberate: distinguishing them would let an attacker confirm which addresses are registered.","operationId":"login","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokensDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Invalid credentials."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Sign in and receive tokens","tags":["Authentication"]}},"/api/auth/refresh":{"post":{"description":"Refresh tokens are single-use and rotated: the presented token is revoked and a new one returned. Presenting an already-used token is treated as evidence of theft and revokes every session descended from that sign-in, forcing re-authentication.","operationId":"refresh","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokensDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Session expired, revoked or reused."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Exchange a refresh token for a new token pair","tags":["Authentication"]}},"/api/auth/switch-organization":{"post":{"description":"Platform administration only. Returns a new token pair scoped to the named organization, so the administrator acts within it under the ordinary tenancy rules rather than bypassing them. Permissions in the target organization derive from the platform flag, not from a role there, so the response to /auth/me will show a full permission set alongside an empty role list. The previous session remains valid. An unknown or suspended organization returns 404, never 403, so the endpoint cannot be used to discover which organizations exist.","operationId":"switchOrganization","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwitchOrganizationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokensDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"404":{"description":"Organization not found or not active."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Issue a session scoped to another organization","tags":["Authentication"]}},"/api/auth/logout":{"post":{"description":"Revokes the token and every token rotated from the same sign-in. Always succeeds, even for an unknown token: reporting otherwise would confirm to the caller whether the token was valid.","operationId":"logout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenDto"}}}},"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"End the session","tags":["Authentication"]}},"/api/auth/forgot-password":{"post":{"description":"Generates a temporary password, replaces the account password with it, revokes every existing session, and emails it to the address given. Signing in with that password then requires an immediate change: until it happens every endpoint except `/auth/me` and `/auth/change-password` returns `403 PASSWORD_CHANGE_REQUIRED`.\n\nAlways returns `200`, whether or not the address belongs to an account and whether or not that account can sign in. Reporting otherwise would make this a membership oracle for the entire platform, reachable with no credential at all.\n\nIf the message cannot be delivered the password change is rolled back — the previous password keeps working — and the failure is logged. The response is unchanged.","operationId":"forgotPassword","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgotPasswordDto"}}}},"responses":{"200":{"description":"Request accepted; nothing is disclosed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Email a temporary password","tags":["Authentication"]}},"/api/auth/change-password":{"post":{"description":"Verifies the current password, stores the new one, and clears any forced-change requirement. Every other session is revoked — changing a password is the standard response to a suspected compromise — and a fresh token pair is returned so the device making the change stays signed in. Access tokens already issued to other devices remain valid until they expire (at most `expiresIn`); their refresh tokens do not.","operationId":"changePassword","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePasswordDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokensDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Current password is incorrect."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Change the signed-in account's password","tags":["Authentication"]}},"/api/auth/me":{"get":{"description":"Returns the signed-in user, the organization the session is scoped to, and the permissions they hold there. Clients should drive their navigation from `permissions` rather than assuming a role name.","operationId":"me","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUserDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid token."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Describe the current session","tags":["Authentication"]}},"/api/auth/me/photo":{"post":{"description":"A profile photo is 0-or-1 per user. Uploading a new one replaces the existing photo — the previous Cloudinary asset is only deleted after the new upload has committed, so a failed replace never destroys a working photo.","operationId":"setProfilePhoto","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Set or replace your profile photo","tags":["Authentication"]},"delete":{"operationId":"removeProfilePhoto","parameters":[],"responses":{"204":{"description":"The photo was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"404":{"description":"No profile photo to remove."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove your profile photo","tags":["Authentication"]}},"/api/users":{"get":{"description":"Returns members of the session's organization only. There is no platform-wide user listing, so this cannot be used to enumerate accounts belonging to other organizations.","operationId":"list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MembershipUserDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List users in the organization","tags":["Users"]},"post":{"description":"Creates a **new** account and its membership together. If the address already belongs to an account this returns `409` rather than attaching it — adding an existing person requires an invitation they accept, so that an organization cannot conscript an unrelated platform user.\n\nOmitting `password` generates a temporary one and emails it to the user, the same way a password reset does: they sign in with it and are required to choose their own password immediately after.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipUserDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"That email address is already registered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create a new user in the organization","tags":["Users"]}},"/api/users/{id}":{"get":{"description":"A user who exists but is not a member of your organization returns `404`, the same as an unknown id.","operationId":"findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipUserDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such user in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Fetch a user in the organization","tags":["Users"]},"patch":{"description":"Profile details only. Activating or deactivating an account is a separate endpoint requiring `user.deactivate`, so a role granted to correct someone’s name does not also confer the power to lock them out.","operationId":"update","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipUserDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such user in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a user’s profile","tags":["Users"]},"delete":{"description":"Restricted to platform administrators, and only for an account with no activity on record — a mistaken invite or a test user. Anyone who has raised, approved, received or issued anything must be deactivated instead, because those records reference them permanently. The caller cannot delete themselves, the platform administrator, or a user who also belongs to another organization.","operationId":"delete","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The account was deleted."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such user in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The user has activity on record, is the caller or the platform administrator, or belongs to another organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Delete a user account","tags":["Users"]}},"/api/users/{id}/status":{"put":{"description":"Deactivation revokes every session the account holds, so access ends at once rather than when the access token expires. The record is retained because approvals and purchase orders reference it permanently.","operationId":"setStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetUserStatusDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipUserDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such user in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Activate or deactivate a user account","tags":["Users"]}},"/api/organizations/{organizationId}/invitations":{"post":{"description":"Invitations are addressed by **email**, never by user id, and the response is identical whether or not that address already has an account — so this cannot be used to discover who is registered on the platform.\n\nA membership is created only when the invitee accepts. There is no outbound email yet: pass the returned `token` to them out of band.","operationId":"invite","parameters":[{"name":"organizationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteMemberDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuedInvitationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"An invitation for that address is already pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Invite someone to join the organization","tags":["Users"]},"get":{"description":"Tokens are never returned here — only at creation.","operationId":"listInvitations","parameters":[{"name":"organizationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvitationDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List pending invitations","tags":["Users"]}},"/api/invitations/{id}/revoke":{"post":{"operationId":"revokeInvitation","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Invitation withdrawn."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such pending invitation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Withdraw a pending invitation","tags":["Users"]}},"/api/invitations/accept":{"post":{"description":"Requires a valid session: the signed-in account’s email must match the invited address, so a leaked token alone cannot be used to join. Creates the membership and grants any role the invitation carried.","operationId":"acceptInvitation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptInvitationDto"}}}},"responses":{"204":{"description":"Membership created."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Invitation not found, expired, or already used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Accept an invitation","tags":["Users"]}},"/api/users/{id}/membership":{"patch":{"description":"Suspends access to this organization only. The account itself, and any membership of another organization, are unaffected.","operationId":"updateMembership","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMembershipDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipUserDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such user in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Suspend or restore a membership","tags":["Users"]}},"/api/users/{id}/roles":{"put":{"description":"The supplied list becomes the complete set of roles, so a role is revoked by omitting it. Roles must belong to your organization — the database enforces this through a composite foreign key, not only the application.","operationId":"assignRoles","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignRolesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipUserDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such user in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Replace the roles a member holds","tags":["Users"]}},"/api/roles":{"get":{"description":"Roles are defined per organization, so each firm can model its own structure without affecting others.","operationId":"list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RoleDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List roles in the organization","tags":["Roles"]},"post":{"description":"Grants a named set of permissions. Unknown permission keys are rejected rather than ignored, so a typo cannot silently produce a role that grants less than intended, and a key outside the caller's own permissions is rejected too, so a role cannot be used to grant more access than its creator holds.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRoleDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A role with that name already exists here, or a permission key is not grantable or not held by the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create a role","tags":["Roles"]}},"/api/roles/{id}":{"get":{"operationId":"findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such role in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Fetch a role","tags":["Roles"]},"patch":{"description":"Supplying `permissionKeys` replaces the role's permissions entirely. System roles may have their permissions adjusted but cannot be renamed, so an organization cannot lose track of the role that grants administration. A permission key outside the caller's own permissions is rejected, so a role cannot be edited to grant more access than its editor holds.","operationId":"update","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRoleDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such role in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Name already used, the role is a system role, or a permission key is not grantable or not held by the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a role","tags":["Roles"]},"delete":{"description":"Restricted to platform administrators. Gated on the platform-admin flag rather than a permission key because a grantable key would land in every tenant’s Administrator role. System roles cannot be deleted, and a role that any member holds or any approval policy routes through is refused rather than stripped, so nobody silently loses access.","operationId":"delete","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The role was deleted."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such role in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The role is a system role, or is held by members or used by an approval policy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Delete a role","tags":["Roles"]}},"/api/permissions":{"get":{"description":"The catalogue of permission keys that can be granted to a role, for building a role editor. Excludes keys published but not yet enforced by any route, since those cannot be attached to a role. Read-only: permission keys are code constants that guards check, so a key invented at runtime would grant nothing. New keys arrive with the module that enforces them.","operationId":"listPermissions","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PermissionDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List assignable permissions","tags":["Roles"]}},"/api/organizations":{"post":{"description":"Restricted to platform administrators. Creating an organization cannot be governed by an organization-scoped permission, because no organization yet exists to scope the check against. The platform-admin flag is set only by the bootstrap command, never through the API.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"An organization already uses that code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create an organization","tags":["Organizations"]},"get":{"description":"Restricted to platform administrators. This is the one endpoint that deliberately crosses tenant lines: it exists so an administrator can find an organization to switch into via `POST /api/auth/switch-organization` without knowing its id by heart.\n\nIt is gated on the platform-admin flag rather than a permission key because a grantable key would land in every tenant’s Administrator role — letting each customer enumerate the platform’s entire client list. Ordered by name; filter with `status`, narrow with `search` (a case-insensitive partial match on name or code) and page with `page` and `limit` (max 100).","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","description":"Restrict to organizations in this state. Omit for all.\n\nUseful for a switcher, which generally wants only the active ones — a\nsuspended organization cannot be switched into.","schema":{"example":"ACTIVE","type":"string","enum":["ACTIVE","INACTIVE"]}},{"name":"search","required":false,"in":"query","description":"Case-insensitive partial match on name or code.\n\nLets a switcher offer type-ahead rather than making an administrator page\nthrough every tenant on the platform.","schema":{"maxLength":100,"example":"acme","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of organizations.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List every organization on the platform","tags":["Organizations"]}},"/api/organizations/{id}":{"get":{"description":"Callers may read only the organization their session is scoped to. Requesting another returns `404` rather than `403`, so the response does not confirm that the other organization exists.","operationId":"findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such organization, or it is outside your session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Fetch an organization","tags":["Organizations"]},"patch":{"description":"The `code` cannot be changed: it appears in documents and external references. Setting `status` to `INACTIVE` prevents members from signing in while retaining all history. `timezone` must be an IANA region name (or `UTC`); it is stored in canonical casing.","operationId":"update","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganizationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such organization, or it is outside your session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update an organization","tags":["Organizations"]}},"/api/organizations/{organizationId}/branches":{"post":{"description":"Branch codes are unique within an organization, so two firms may each have a branch coded `HQ`.","operationId":"create","parameters":[{"name":"organizationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBranchDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"The organization is outside your session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A branch with that code already exists here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create a branch","tags":["Organizations"]},"get":{"operationId":"list","parameters":[{"name":"organizationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BranchDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"The organization is outside your session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List branches in an organization","tags":["Organizations"]}},"/api/branches/{id}":{"get":{"description":"Scoped to the session automatically. A branch belonging to another organization returns `404`, identically to one that does not exist.","operationId":"findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such branch in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Fetch a branch","tags":["Organizations"]},"patch":{"description":"Closing a site sets `status` to `INACTIVE`; cost allocations and stock movements that reference the branch remain valid.","operationId":"update","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBranchDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such branch in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a branch","tags":["Organizations"]}},"/api/departments":{"get":{"description":"Returns departments belonging to the organization your session is scoped to. There is no cross-organization listing.","operationId":"list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DepartmentDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List departments","tags":["Master Data"]},"post":{"description":"The department is created in **your** organization — the owning organization comes from your session, never from the request body. Codes are unique per organization, so two firms may each have a `QS`.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDepartmentDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A department with that code already exists here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create a department","tags":["Master Data"]}},"/api/departments/{id}":{"get":{"description":"A department belonging to another organization returns `404`, identically to one that does not exist.","operationId":"findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such department in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Fetch a department","tags":["Master Data"]},"patch":{"description":"Updates the name, description, or status. `code` cannot be changed — it is quoted in documents and referenced by downstream records.\n\nSetting `status` to `INACTIVE` retires the department from new selections while leaving every historical reference intact. There is deliberately no delete endpoint.","operationId":"update","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDepartmentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such department in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a department","tags":["Master Data"]}},"/api/cost-centres":{"get":{"description":"Returns cost centres belonging to the organization your session is scoped to, ordered by code.","operationId":"list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CostCentreDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List cost centres","tags":["Master Data"]},"post":{"description":"Created in **your** organization — ownership comes from your session, never from the request body.\n\nA cost centre groups expenditure for reporting; it is **not** a project. A future Project may reference one, but projects carry schedules, teams and a work breakdown that a cost centre does not.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCostCentreDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostCentreDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A cost centre with that code already exists here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create a cost centre","tags":["Master Data"]}},"/api/cost-centres/{id}":{"get":{"description":"A cost centre belonging to another organization returns `404`, identically to one that does not exist.","operationId":"findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostCentreDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such cost centre in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Fetch a cost centre","tags":["Master Data"]},"patch":{"description":"Updates the name, description, or status. `code` cannot be changed.\n\nSetting `status` to `INACTIVE` stops the cost centre being selected for new spend while leaving historical cost allocations intact. There is deliberately no delete endpoint.","operationId":"update","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCostCentreDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostCentreDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such cost centre in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a cost centre","tags":["Master Data"]}},"/api/requisition-types":{"get":{"description":"Returns requisition types belonging to the organization your session is scoped to, ordered by code.","operationId":"list","parameters":[{"name":"include","required":false,"in":"query","description":"`usage` adds line counts and who last changed each type.","schema":{"type":"string","enum":["usage"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RequisitionTypeDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List requisition types","tags":["Master Data"]},"post":{"description":"Created in **your** organization — ownership comes from your session, never from the request body.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRequisitionTypeDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionTypeDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A requisition type with that code already exists here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create a requisition type","tags":["Master Data"]}},"/api/requisition-types/{id}":{"get":{"description":"A requisition type belonging to another organization returns `404`, identically to one that does not exist.","operationId":"findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionTypeDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition type in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Fetch a requisition type","tags":["Master Data"]},"patch":{"description":"Updates the name, description, status, route or order. `code` cannot be changed.\n\nChanging `route` needs `requisition_type.manage` and applies to requisitions submitted from now on; lines already submitted keep theirs.\n\nSetting `status` to `INACTIVE` stops the type being selected on new requisitions while leaving existing ones intact. There is deliberately no delete endpoint.","operationId":"update","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRequisitionTypeDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionTypeDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition type in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a requisition type","tags":["Master Data"]},"delete":{"description":"Only a type no requisition or line has ever used. A type in use returns `409 REQUISITION_TYPE_IN_USE`; deactivate it instead.","operationId":"remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition type in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The type is in use.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Delete an unused requisition type","tags":["Master Data"]}},"/api/requisition-types/{id}/route-impact":{"get":{"description":"Lines on requisitions already submitted keep the route they were submitted with. Settings shows this count before a route is changed.","operationId":"routeImpact","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteImpactDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition type in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"How many submitted lines a route change would leave alone","tags":["Master Data"]}},"/api/requisition-routes/settings":{"get":{"operationId":"get","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionRouteSettingsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Whether requisition routes are switched on","tags":["Master Data"]},"patch":{"description":"While off, every line is submitted as STOCK and Payments to make is hidden. Lines already submitted keep the route they were submitted with either way.","operationId":"update","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRequisitionRouteSettingsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionRouteSettingsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Switch requisition routes on or off","tags":["Master Data"]}},"/api/staff":{"get":{"description":"One row per member of **your** organization, with their departmental assignments nested. Filter with `departmentId`, `status` and `search` (name, email, job title or employee number); page with `page` and `limit` (max 100).\n\nA member whose department has never been recorded appears with an empty `departments` array — that is the honest answer, not an error.","operationId":"list","parameters":[{"name":"departmentId","required":false,"in":"query","description":"Restrict to members assigned to one department.","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","description":"Restrict to members whose *membership* has this status.","schema":{"type":"string","enum":["ACTIVE","INACTIVE"]}},{"name":"search","required":false,"in":"query","description":"Match against name, email, job title or employee number.","schema":{"maxLength":100,"type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of staff.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StaffMemberDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List the staff directory","tags":["Staff"]}},"/api/staff/org-chart":{"get":{"description":"Every department with its head and the number of members actively assigned to it.\n\nTwo levels, deliberately: departments and their members. There is no person-to-person reporting chain — see the README for why that is deferred rather than missing.\n\n`headAssignmentInactive` flags a department whose named head no longer works there. It is surfaced rather than silently cleared, so a reshuffle does not quietly decapitate departments.","operationId":"orgChart","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrgChartDepartmentDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"The departmental org chart","tags":["Staff"]}},"/api/staff/{membershipId}":{"get":{"description":"Addressed by **membership** id, not user id: a user is a global identity that may belong to several firms, while a membership belongs to exactly one, which is what makes the lookup tenant-safe.\n\nA member of another organization returns 404, never 403 — a 403 would confirm the membership exists.","operationId":"findOne","parameters":[{"name":"membershipId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffMemberDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such member of staff in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get one member of staff","tags":["Staff"]}},"/api/staff/{membershipId}/departments":{"post":{"description":"Assigning somebody who was previously assigned and deactivated **reactivates that row** rather than creating a second one, so their assignment history stays single-valued. The status code distinguishes the two: 201 for a new assignment, 200 for a reactivation.\n\nA member may belong to several departments — a quantity surveyor serving Construction and Civils is an ordinary arrangement. At most one may be `isPrimary`; naming a new primary moves the flag.\n\n**This grants nothing.** It records where the person works.","operationId":"assignDepartment","parameters":[{"name":"membershipId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignDepartmentDto"}}}},"responses":{"200":{"description":"An existing assignment was reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffAssignmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such member of staff, or no such department.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The department is INACTIVE and cannot take new assignments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Assign a member to a department","tags":["Staff"]}},"/api/staff/{membershipId}/departments/{departmentId}":{"patch":{"description":"Sets `isPrimary` or `status`. Ending an assignment sets `INACTIVE` rather than deleting it, so who worked in which department, and when, stays answerable — there is no delete.\n\nAn INACTIVE assignment cannot be the primary one: the constraint that enforces \"one primary\" only counts active rows, so an inactive primary would be configuration nobody can reach.","operationId":"updateAssignment","parameters":[{"name":"membershipId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"departmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStaffAssignmentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffAssignmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such member of staff, or no such assignment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"An INACTIVE assignment cannot be the primary one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update one departmental assignment","tags":["Staff"]}},"/api/staff/{membershipId}/employment":{"patch":{"description":"`jobTitle` is free text: there is deliberately no controlled vocabulary, because nothing routes or aggregates on it.\n\n`employeeNumber` is unique within your organization and **immutable once set** — it is quoted on paperwork, so rewriting it would orphan documents already signed against it. Sending a different one returns 409.","operationId":"updateEmployment","parameters":[{"name":"membershipId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmploymentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffMemberDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such member of staff in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The employee number is already used, or is already set to a different value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Record job title and employee number","tags":["Staff"]}},"/api/staff/assignments/{assignmentId}/attachments":{"post":{"description":"Uploaded to Cloudinary and recorded here. An assignment in another organization returns 404, never 403.","operationId":"attachToAssignment","parameters":[{"name":"assignmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"caption":{"type":"string"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such assignment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Attach a supporting document to a staff assignment","tags":["Staff"]},"get":{"operationId":"listAssignmentAttachments","parameters":[{"name":"assignmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such assignment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a staff assignment’s attachments","tags":["Staff"]}},"/api/staff/assignments/{assignmentId}/attachments/{attachmentId}":{"delete":{"operationId":"removeAssignmentAttachment","parameters":[{"name":"assignmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"attachmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The attachment was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such assignment or attachment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a staff assignment’s attachment","tags":["Staff"]}},"/api/departments/{departmentId}/staff":{"get":{"description":"Members with an **active** assignment to this department. The same page shape as `GET /staff`, filtered to one department.\n\nA department in another organization returns 404, never 403.","operationId":"roster","parameters":[{"name":"departmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","description":"Restrict to members whose *membership* has this status.","schema":{"type":"string","enum":["ACTIVE","INACTIVE"]}},{"name":"search","required":false,"in":"query","description":"Match against name, email, job title or employee number.","schema":{"maxLength":100,"type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the department’s staff.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StaffMemberDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such department in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a department’s roster","tags":["Staff"]}},"/api/departments/{departmentId}/head":{"patch":{"description":"The nominee must have an **active assignment to this department** — a head who does not work there would make the org chart lie. Send `null` to record a vacancy, which is a real state and better than an interim fabrication.\n\n**Naming a head grants them nothing.** They do not thereby see across departments, gain authority over the department’s spending, or become known to any guard. Widening access is granted by permission, never derived from a data relationship.","operationId":"setHead","parameters":[{"name":"departmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDepartmentHeadDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgChartDepartmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such department, or no such member of staff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The nominee has no active assignment to this department.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Name or clear a department head","tags":["Staff"]}},"/api/projects":{"get":{"description":"Returns projects belonging to the organization your session is scoped to, ordered by project code A→Z, with branch, cost centre and department names joined so a list view needs no follow-up requests.\n\nFilter with `status`, `branchId` and `costCentreId`; page with `page` and `limit` (max 100). Reorder with `sortBy` (`projectCode`, `name`, `createdAt`, `updatedAt`) and `sortDirection` — e.g. `sortBy=createdAt&sortDirection=desc` for the newest projects first.","operationId":"list","parameters":[{"name":"sortBy","required":false,"in":"query","description":"Column to order by, in `sortDirection`. Omitted, the list is ordered by\nproject code A→Z and `sortDirection` is ignored — the order this endpoint\nhas always had, which existing callers rely on.","schema":{"example":"createdAt","type":"string","enum":["projectCode","name","createdAt","updatedAt"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["PLANNED","ACTIVE","ON_HOLD","COMPLETED","CANCELLED"]}},{"name":"branchId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"costCentreId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of projects.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProjectDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List projects","tags":["Projects"]},"post":{"description":"The project is created in **your** organization — ownership comes from your session, never from the request body. Project codes are unique per organization, so two firms may each run a `KROC-001`.\n\nProjects start as `PLANNED`; move them with `PATCH /projects/{id}/status`.\n\nAny branch, cost centre or department referenced must belong to your organization — enforced by the database, not only by this endpoint.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A project with that code already exists here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create a project","tags":["Projects"]}},"/api/projects/summary":{"get":{"description":"Counts, contract value, budget and committed-cost totals for every project matching `status` and `branchId` — not one page.\n\nMoney is a decimal string **per currency** and is never converted. `budget` is `null` unless you hold `budget.view`, and `committed` is `null` unless you hold `purchase_order.view`: the summary never shows money its source registers would not.","operationId":"summary","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["PLANNED","ACTIVE","ON_HOLD","COMPLETED","CANCELLED"]}},{"name":"branchId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSummaryDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Portfolio summary","tags":["Projects"]}},"/api/projects/{id}":{"get":{"description":"A project belonging to another organization returns `404`, identically to one that does not exist.","operationId":"findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Fetch a project","tags":["Projects"]},"patch":{"description":"Updates descriptive, commercial and scheduling fields.\n\n`projectCode` cannot be changed — it appears on contracts and will be referenced by requisitions. `status` cannot be changed here either: lifecycle moves go through `PATCH /projects/{id}/status`, so the transition rules cannot be bypassed by an ordinary edit. Sending either field returns `400`.","operationId":"update","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`STALE_WRITE`: `expectedUpdatedAt` was sent and the project has been saved since. Nothing was written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a project","tags":["Projects"]}},"/api/projects/{id}/status":{"patch":{"description":"Valid transitions:\n\n```\nPLANNED   → ACTIVE, CANCELLED\nACTIVE    → ON_HOLD, COMPLETED, CANCELLED\nON_HOLD   → ACTIVE, CANCELLED\nCOMPLETED → (terminal)\nCANCELLED → (terminal)\n```\n\nAnything else returns `409` naming the legal moves. Becoming `ACTIVE` requires a start date; `COMPLETED` requires `actualCompletionDate`, which is rejected for any other target.\n\nThere is no delete endpoint: a project that will not proceed is moved to `CANCELLED`, so purchase orders and cost allocations that reference it stay intact.","operationId":"changeStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeProjectStatusDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"That lifecycle transition is not permitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Change a project’s lifecycle status","tags":["Projects"]}},"/api/projects/{projectId}/attachments":{"post":{"description":"Site survey imagery (drone orthomosaics, progress photography) and project documents. Survey metadata — `latitude`, `longitude`, `capturedAt` — is optional; coordinates must be sent as a pair. `capturedAt` is when the image was taken on site, which is not the upload time.","operationId":"attachToProject","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"caption":{"type":"string"},"latitude":{"type":"string","example":"0.315700"},"longitude":{"type":"string","example":"32.581100"},"capturedAt":{"type":"string","example":"2026-09-14T08:30:00.000Z"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Attach a file to a project","tags":["Projects"]},"get":{"description":"Newest first, so a survey card can render the most recent capture without sorting. A plain array, not a page.","operationId":"listProjectAttachments","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"A project's attachments","tags":["Projects"]}},"/api/projects/{projectId}/attachments/{attachmentId}":{"delete":{"description":"Deletes the row and the Cloudinary asset together. There is no soft delete.","operationId":"removeProjectAttachment","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"attachmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project or attachment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove one of a project's attachments","tags":["Projects"]}},"/api/projects/{projectId}/members":{"get":{"description":"Returns everyone assigned to the project, by name, including assignments that have been deactivated — a roster that hid ended assignments would misrepresent the project’s history.\n\nTwo statuses are reported separately: `status` is the assignment, `organizationMembershipStatus` the person’s standing in the organization. Someone suspended from the organization keeps their assignments, so both are needed to tell \"off this project\" from \"out of the organization\".\n\nA project in another organization returns `404`, identically to one that does not exist.","operationId":"list","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectMemberDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List the members assigned to a project","tags":["Project Members"]},"post":{"description":"The body names an **organization membership**, not a user: a membership belongs to exactly one organization, so the database can verify tenancy through a composite foreign key. Both the project and the membership must belong to your organization, and that is enforced by the database, not only by this endpoint.\n\n**This grants no permissions.** Assigning someone records that they are working on the project; what they may do continues to come from the roles on their organization membership.\n\nAssigning someone already assigned returns `409`. Re-assigning someone whose assignment was deactivated restores it, keeping the date they first joined.\n\nProjects that are `COMPLETED` or `CANCELLED` accept no new assignments; existing ones stay readable and can still be ended.","operationId":"assign","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignProjectMemberDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectMemberDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Already assigned, or the project is completed or cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Assign a member to a project","tags":["Project Members"]}},"/api/projects/{projectId}/members/{id}":{"patch":{"description":"Sets the assignment to `INACTIVE` to end it, or back to `ACTIVE` to restore it.\n\n**This affects the assignment only.** The person’s membership of the organization, their roles and their access to the system are untouched — taking someone off a project says nothing about their employment.\n\nThere is no delete endpoint: who was assigned to a project, and when, is referenced by the requisitions, approvals and cost allocations that come later. Permitted on completed and cancelled projects, so a closed job can still be tidied up.","operationId":"update","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"id","required":true,"in":"path","description":"Id of the assignment.","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectMemberDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectMemberDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such assignment on that project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"End or restore an assignment","tags":["Project Members"]}},"/api/projects/{projectId}/reopen-requests":{"post":{"description":"Nothing changes until someone else approves it. One request per project may wait at a time.","operationId":"request","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestProjectReopenDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectReopenRequestDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The project is not completed, or already has a request waiting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Ask for a completed project to be reopened","tags":["Projects"]},"get":{"description":"Lets the requester see whether a request is still waiting.","operationId":"listForProject","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of reopen requests.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProjectReopenRequestDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List one project’s reopen requests","tags":["Projects"]}},"/api/project-reopen-requests":{"get":{"description":"Newest first. Filter by `status`: `PENDING` is the approver’s queue.","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of reopen requests.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProjectReopenRequestDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List reopen requests","tags":["Projects"]}},"/api/project-reopen-requests/{requestId}/approve":{"post":{"description":"By someone other than the requester. Clears the actual completion date.","operationId":"approve","parameters":[{"name":"requestId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectReopenRequestDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such reopen request in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The request has already been decided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Approve a reopen request, making the project active again","tags":["Projects"]}},"/api/project-reopen-requests/{requestId}/reject":{"post":{"description":"A reason is required. The project stays completed.","operationId":"reject","parameters":[{"name":"requestId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectReopenDecisionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectReopenRequestDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such reopen request in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The request has already been decided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Reject a reopen request","tags":["Projects"]}},"/api/boqs/import-template":{"get":{"description":"An empty workbook with an **Instructions** sheet and the two sheets the import reads: **Sections** (Section Code*, Section Name*, Parent Section Code, Description) and **Items** (Section Code*, Item Code*, Description*, Unit*, Quantity*, Rate*). Code columns are formatted as text so Excel keeps a leading zero.","operationId":"importTemplate","parameters":[],"responses":{"200":{"description":"","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Download the BOQ import template (.xlsx)","tags":["BOQ"]}},"/api/boqs/{boqId}/export":{"get":{"description":"Three sheets. **Bill** is the printed bill: each section as a band, its items, and a subtotal after its sub-sections, ending in the bill total — all figures from the database, the same ones the API returns.\n\n**Sections** and **Items** repeat the content in exactly the import layout, so an exported bill can be imported into another bill unchanged (an \"Amount\" column is included for reading and ignored on import).\n\nNeeds only `boq.view`: the file shows nothing the listing does not. Named `TetraBuild_{ProjectCode}_{BoqCode}_Bill_of_Quantities.xlsx`.","operationId":"export","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such bill of quantities in your organization.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Export a bill of quantities (.xlsx)","tags":["BOQ"]}},"/api/boqs/{boqId}/import":{"post":{"description":"Upload a workbook in the template’s layout as the multipart field `file` (at most 5 MB, 2,000 sections and 10,000 items).\n\n**Additive.** Only creates: a section or item code that already exists in the bill is reported, never overwritten. Items may go into sections from the file or already in the bill; a section’s parent likewise.\n\n**All or nothing.** Every row is checked with the same rules as the create endpoints, plus duplicates, parents, loops, the 10-level depth cap, and whether each line’s amount fits. If anything is wrong nothing is written and the response is `422` `BOQ_IMPORT_INVALID` with `errors` — each with `sheet`, `row`, `column` and `message` — and `errorCount`.\n\n**`?dryRun=true`** runs the same checks and returns `200` with the result whether or not the file is valid, writing nothing — the \"Validate\" step.\n\nNumbers typed in Excel are read at Excel’s own 15-digit precision; a value with more than 4 decimal places is reported, never rounded. Formula cells use their saved result.\n\nRejected with `409` on a `CLOSED` bill or a `COMPLETED`/`CANCELLED` project, and with `409` `BOQ_IMPORT_CONFLICT` if another user adds one of the same codes while the import runs. Recorded in the project’s audit trail.","operationId":"import","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"dryRun","required":false,"in":"query","description":"Validate only: report what would be imported, and every problem, without\nwriting anything. Accepts `true`/`false` (and `1`/`0`).","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoqImportResultDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such bill of quantities in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The bill is CLOSED, the project is finished, or a code was taken concurrently.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"422":{"description":"The file has problems; nothing was imported. Body carries `errors` and `errorCount`."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Import sections and items from a workbook","tags":["BOQ"]}},"/api/boqs/{boqId}":{"get":{"description":"Returns the bill with its derived totals: `totalAmount` is the sum of every item’s server-calculated amount, `itemCount` and `sectionCount` the sizes of the bill.\n\nTotals are computed on read from a single aggregate query and are never stored, so they cannot disagree with the lines they summarise. An empty bill reports `0.0000`.\n\nA bill in another organization returns `404`, identically to one that does not exist.","operationId":"findOne","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoqDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such bill of quantities in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Retrieve a bill of quantities","tags":["BOQ"]},"patch":{"description":"Updates the name, description or currency.\n\n`boqCode` is immutable and `status` moves only through `PATCH /boqs/{boqId}/status`, which validates the transition. Sending either returns `400` rather than being silently ignored, which is what makes the lifecycle rules unbypassable.\n\nA `CLOSED` bill rejects every modification with `409`; it stays readable.","operationId":"update","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBoqDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoqDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such bill of quantities in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The bill is CLOSED and can no longer be modified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a bill’s metadata","tags":["BOQ"]}},"/api/boqs/{boqId}/status":{"patch":{"description":"Valid transitions:\n\n```\nDRAFT  → ACTIVE, CLOSED\nACTIVE → CLOSED\nCLOSED → (terminal)\n```\n\nAnything else returns `409` naming the legal moves. Setting the current status again succeeds unchanged, so retrying a request that already applied does not fail.\n\n`CLOSED` is the retirement path in place of a delete: a closed bill accepts no further change to its metadata, structure or prices, and stays fully readable.\n\nPermitted even on a `COMPLETED` or `CANCELLED` project, unlike creation — a finished job must not leave bills that can never be closed out.","operationId":"changeStatus","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBoqStatusDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoqDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such bill of quantities in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"That lifecycle transition is not permitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Move a bill through its lifecycle","tags":["BOQ"]}},"/api/boqs/{boqId}/sections":{"get":{"description":"**This hierarchy is the WBS.** Root sections — those with no parent — are what a printed bill calls \"Bill 01\"; beneath them sit sections, sub-sections and work packages to a depth of 10 levels.\n\nReturned **whole and unpaginated**: page two of a hierarchy is not a hierarchy. A bill holds tens of sections, where its items — which are paginated — run to thousands. The whole tree costs two queries regardless of its size or depth.\n\nEach node carries `subtotalAmount` and `itemCount` for **its entire subtree**, so a parent reports the value of the work beneath it. Both are derived on read, never stored.\n\nChildren are ordered by `sortOrder`, then `sectionCode`, then `id` — a total order, so the tree is byte-identical between calls.","operationId":"sectionTree","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BoqSectionTreeDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such bill of quantities in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Retrieve the bill’s work breakdown as a tree","tags":["BOQ"]},"post":{"description":"Omit `parentSectionId` for a root section, or name a section **of the same bill** to nest beneath it.\n\nThe parent is validated three ways: a parent in another bill or another tenant returns `404` (identically, so the response cannot be used to probe for another firm’s data); a parent that would exceed the 10-level cap returns `409`; and the database itself refuses a cross-bill parent through a composite foreign key, so a bulk import cannot write one either.\n\n`parentSectionId` is **immutable** — there is no re-parenting operation, which is what makes a cycle in the hierarchy unreachable rather than merely guarded against.\n\n`sortOrder` defaults to the end of the sibling list, leaving gaps so a later insertion needs no renumbering. `sectionCode` is unique within the bill; a duplicate returns `409`.\n\nRejected with `409` on a `CLOSED` bill or a `COMPLETED`/`CANCELLED` project.","operationId":"createSection","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBoqSectionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoqSectionDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such bill in your organization, or no such parent section in this bill.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Duplicate section code, depth cap exceeded, or the bill is CLOSED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a section to the bill’s work breakdown","tags":["BOQ"]}},"/api/boqs/{boqId}/sections/{sectionId}":{"patch":{"description":"Updates the name, description or position.\n\n`sectionCode` and `parentSectionId` are both immutable: the code is a structural identifier quoted in the bill, and the parent cannot change because re-parenting is the only operation that could introduce a cycle. Sending either returns `400`.\n\nA section belonging to a different bill returns `404`.","operationId":"updateSection","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"sectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBoqSectionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoqSectionDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such section in this bill of quantities.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The bill is CLOSED and can no longer be modified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a section","tags":["BOQ"]},"delete":{"description":"Only a section with **no sub-sections and no items** can be deleted; otherwise `409` `BOQ_SECTION_NOT_EMPTY`. Deletion is deliberately not recursive — removing a section that holds priced work would silently take money out of the bill. Move or delete its contents first.\n\nRefused with `409` on a `CLOSED` bill.","operationId":"deleteSection","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"sectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Deleted."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such section in this bill of quantities.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The section is not empty, or the bill is CLOSED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Delete an empty section","tags":["BOQ"]}},"/api/boqs/{boqId}/sections/{sectionId}/move":{"post":{"description":"Re-parents a section under another section **of the same bill**, or to the top level with `parentSectionId: null`. Its sub-sections and items move with it.\n\nRefused with `409` `BOQ_SECTION_CYCLE` when the new parent is the section itself or one of its descendants, and `409` `BOQ_SECTION_DEPTH_EXCEEDED` when the deepest part of the moved subtree would pass the 10-level cap. A parent not in this bill returns `404`.\n\n`sortOrder` positions it among its new siblings; omitted, it goes to the end (or keeps its place, when the parent is unchanged). Moves in the same bill are serialised by a row lock, so two concurrent moves cannot together form a loop.","operationId":"moveSection","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"sectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveBoqSectionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoqSectionDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such section, or no such parent, in this bill.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Would form a cycle, exceed the depth cap, or the bill is CLOSED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Move a section, with everything beneath it","tags":["BOQ"]}},"/api/boqs/{boqId}/items":{"get":{"description":"Paginated with `page` and `limit`: a real bill runs to thousands of lines, so this collection is never returned unbounded. Filter to one section with `sectionId` — descendant sections are not included.\n\nOrdered by the tree’s shape, so a page reads the way the bill is printed: section depth and position, then the item’s position, code and id. Ending on a unique column makes the order total, which is what keeps pagination safe — rows tied on every other key could otherwise be served twice or skipped between pages.\n\n`amount` on each line is server-calculated — see the create endpoint.","operationId":"listItems","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"sectionId","required":false,"in":"query","description":"Restrict to one section. Descendant sections are not included.","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the bill’s items.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BoqItemDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such bill of quantities in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List the bill’s items","tags":["BOQ"]}},"/api/boqs/{boqId}/items/{itemId}":{"get":{"description":"An item belonging to a different bill — or a different organization — returns `404`, identically to one that does not exist.","operationId":"findItem","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"itemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoqItemDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such item in this bill of quantities.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Retrieve one BOQ item","tags":["BOQ"]},"patch":{"description":"Updates the description, unit, quantity, rate, position or section. Changing `quantity` or `rate` makes the database recompute `amount`; the response carries the new value.\n\n`sectionId` moves the line to another section **of the same bill** (`400` otherwise); without a `sortOrder` it goes to the end of the new section.\n\n`itemCode` and `amount` are immutable or server-owned, so sending either returns `400`: the code is a contractual reference, and the amount is the database’s to compute.","operationId":"updateItem","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"itemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBoqItemDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoqItemDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such item in this bill of quantities.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The bill is CLOSED and can no longer be modified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a BOQ item","tags":["BOQ"]},"delete":{"description":"Removes a priced line from any bill that is not `CLOSED` — including an ACTIVE one, since a line measured in error must be removable.\n\nRefused with `409` `BOQ_ITEM_IN_USE` while a budget line draws against the item: the budget is financial history and is never changed as a side effect. Setting the quantity to zero is the alternative.\n\nRecorded in the project’s audit trail with the line’s code, quantity, rate and amount, since nothing else remains to show it existed.","operationId":"deleteItem","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"itemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Deleted."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such item in this bill of quantities.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A budget line references the item, or the bill is CLOSED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Delete a BOQ item","tags":["BOQ"]}},"/api/boqs/{boqId}/sections/{sectionId}/items":{"post":{"description":"**`amount` is calculated by the server and cannot be supplied.** It is a PostgreSQL generated column defined as `quantity × rate`, so `quantity: \"100\"` with `rate: \"25000\"` always stores `2500000.0000` — sending an `amount` returns `400`, and even a direct database write is refused. Changing quantity or rate recomputes it.\n\n`quantity` and `rate` are decimal **strings**, never JSON numbers: a number has already lost exactness before the server sees it, so one is rejected with `400`. Both permit at most 14 integer and 4 decimal digits — exactly what the column holds, so an oversized value is a `400` rather than an overflow. Negative values are rejected.\n\n`unit` is free text (`m`, `m3`, `kg`, `tonne`, `sum`, `item`), not a fixed list. `itemCode` is your own numbering, unique within the bill, immutable, and **case-preserved** — `02.01.03a` stays as written.\n\nThe section must belong to this bill: one from another bill returns `400`, and the database enforces the same rule through two composite foreign keys.\n\nRejected with `409` on a `CLOSED` bill or a `COMPLETED`/`CANCELLED` project.","operationId":"createItem","parameters":[{"name":"boqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"sectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBoqItemDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoqItemDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such bill of quantities in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Duplicate item code, or the bill is CLOSED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a priced line under a section","tags":["BOQ"]}},"/api/projects/{projectId}/boqs":{"get":{"description":"A project may hold several bills — a main contract, a variation bill, a subcontract package — so this is a paginated collection. Filter by `status`; page with `page` and `limit`.\n\nEach bill carries `totalAmount` and `itemCount`, gathered for the whole page in one aggregate query rather than one per row.\n\nOrdered by `boqCode`. A project in another organization returns `404`, identically to one that does not exist.","operationId":"list","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","ACTIVE","CLOSED"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the project’s bills of quantities.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BoqDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s bills of quantities","tags":["BOQ"]},"post":{"description":"The bill starts in `DRAFT`. `boqCode` is unique **within the project** — two projects may each have a `MAIN` bill — is normalised to upper case, and is immutable once set; a duplicate returns `409`.\n\nA `COMPLETED` or `CANCELLED` project accepts no new bills (`409`). Existing bills stay readable and can still be closed.\n\nSections and items are added through `/boqs/{boqId}/…` once the bill exists.","operationId":"create","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBoqDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoqDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A bill with that code already exists on this project, or the project is COMPLETED/CANCELLED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create a bill of quantities for a project","tags":["BOQ"]}},"/api/budgets/{budgetId}":{"get":{"description":"`totalAmount` is the sum of the budget’s line amounts and `lineCount` the number of lines, both computed by the database on every read. Neither is stored: a persisted total is a second source of truth that disagrees with its own lines the first time one is written outside the service.\n\nAn empty budget reports `\"0.00\"`, not `\"0\"` — the scale is uniform so a client parsing decimal strings never special-cases zero.\n\nA budget in another organization returns `404`, identically to one that does not exist: a `403` would confirm it exists and disclose the platform’s client list.","operationId":"findOne","parameters":[{"name":"budgetId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such budget in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a budget with its derived totals","tags":["Budgets"]},"patch":{"description":"`budgetCode` and `status` are both rejected here with `400`. The code is immutable once set, and the status moves only through `PATCH /budgets/{budgetId}/status` — which is what makes the transition rules unbypassable.\n\nA `CLOSED` budget accepts no further change (`409`) but stays fully readable. Editing a budget on a `COMPLETED` or `CANCELLED` project is permitted: correcting a delivered project’s records is legitimate, even though authorizing new expenditure on it is not.","operationId":"update","parameters":[{"name":"budgetId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBudgetDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, or an immutable field (`budgetCode`, `status`) was sent."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such budget in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The budget is `CLOSED` and can no longer be modified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a budget’s metadata","tags":["Budgets"]}},"/api/budgets/{budgetId}/status":{"patch":{"description":"`DRAFT → ACTIVE, CLOSED`; `ACTIVE → CLOSED`; `CLOSED` is terminal. Anything else returns `409` naming the legal moves. Setting the current status again succeeds unchanged, so retrying a request that already applied does not fail.\n\n**At most one `ACTIVE` budget per project.** Activating a second one returns `409`: close the current budget first, then activate the replacement — which is how a revision works, with no versioning machinery. Enforced by a partial unique index, so a bulk import cannot leave two either.\n\nA dedicated route rather than a field on the general update, because `ACTIVE` is the moment a budget becomes financially authoritative. Permitted even on a terminal project, so a finished job never leaves budgets that can never be closed out.","operationId":"changeStatus","parameters":[{"name":"budgetId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBudgetStatusDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such budget in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Illegal transition, or the project already has an `ACTIVE` budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Move a budget through its lifecycle","tags":["Budgets"]}},"/api/budgets/{budgetId}/lines":{"get":{"description":"Always paginated: a budget drawn against a large bill runs to thousands of lines, so an unbounded read would be a table scan served to a browser. Filter with `boqId` or `costCentreId`.\n\nOrdered by `sortOrder`, then `id`. Ending on a unique column makes the order **total**, which is what keeps pagination safe: rows tied on `sortOrder` could otherwise swap between pages and be served twice or skipped.\n\nEach line carries its BOQ item’s code, description and **current** `boqItemAmount` joined in, beside the line’s own `amount`. The two are independent by design, so a difference between them is a variance to report rather than an inconsistency: the bill measures work, the budget authorizes money.\n\nEach line also carries `exposure`: what **SUBMITTED** requisitions have requested against it, and what remains. Derived on read and stored nowhere — a requisition requests, it does not commit, so nothing here reserves or blocks budget and `remainingAmount` may be negative.","operationId":"listLines","parameters":[{"name":"budgetId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"boqId","required":false,"in":"query","description":"Restrict to lines drawing against one bill.","schema":{"format":"uuid","type":"string"}},{"name":"costCentreId","required":false,"in":"query","description":"Restrict to lines carrying one cost centre.","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the budget’s lines.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BudgetLineDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such budget in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a budget’s lines","tags":["Budgets"]},"post":{"description":"`budget.update`, not `budget.create`: adding a line modifies the budget.\n\n`boqItemId` is **optional**. Omit it for expenditure the bill does not measure — preliminaries, site overheads, contingency, professional fees — which are ordinary budget lines rather than an edge case.\n\nWhen supplied, the item must belong to the **same project** as this budget and to your organization (`400` otherwise, with one message for all three cases so the response never confirms another tenant’s records exist), and its bill must be `ACTIVE` (`409` otherwise — a `DRAFT` bill is still being priced, and a `CLOSED` one is retired work). Both rules are also held by composite foreign keys, so a cross-project or cross-tenant line is unrepresentable rather than merely refused.\n\n`amount` is a decimal **string**, never a JSON number: a number has already lost exactness before the server sees it. At most 16 integer and 2 decimal digits, so an oversized value is a `400` rather than a `500`. Zero is accepted; negative is not.\n\nOne line per BOQ item per budget — a second returns `409`. `organizationId`, `projectId`, `budgetId` and `boqId` are never accepted in the body; the server derives every one of them.","operationId":"createLine","parameters":[{"name":"budgetId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBudgetLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, or the BOQ item or cost centre is not usable from this budget."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such budget in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The budget is `CLOSED`, the project is terminal, the bill is not `ACTIVE`, or the item is already budgeted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a line to a budget","tags":["Budgets"]}},"/api/budgets/{budgetId}/lines/{lineId}":{"patch":{"description":"`boqItemId` is rejected with `400`. Which bill line an authorization draws against is the line’s identity, not an editable attribute: re-pointing it would silently move money between work items and invalidate any variance already reported.\n\nA `CLOSED` budget accepts no change (`409`). Editing a line on a `COMPLETED` or `CANCELLED` project is permitted, unlike adding one.","operationId":"updateLine","parameters":[{"name":"budgetId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBudgetLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, `boqItemId` was sent, or the cost centre is not usable."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such budget or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The budget is `CLOSED` and can no longer be modified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a budget line","tags":["Budgets"]}},"/api/budgets/{budgetId}/transfers":{"post":{"description":"Moves `amount` from `fromLineId` to `toLineId` by recording a variation on each — `from.variationAmount −= amount`, `to.variationAmount += amount` — in **one transaction**, with both lines locked. The original `amount` of each line is untouched.\n\nWith `adjustForecast` (default `true`) the forecasts move by the same amount, so a transfer does not create a variance it did not cause. Send `false` to move the budget alone.\n\nBoth lines must belong to this budget (`400`, one message for every case) and differ (`400`). The giving line’s revised budget may not go below zero (`409 INSUFFICIENT_LINE_BUDGET`), nor its forecast when it moves (`409 INSUFFICIENT_LINE_FORECAST`). A `CLOSED` budget refuses transfers (`409 BUDGET_CLOSED`).\n\nRecorded on the project’s audit trail in the same transaction, with `reason` as its description and `reference` (a VO or instruction number) as its reference.","operationId":"transfer","parameters":[{"name":"budgetId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBudgetTransferDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetTransferResultDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, the two lines are the same, or a line is not on this budget."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such budget in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The budget is `CLOSED`, or the giving line lacks the revised budget or forecast to give.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Transfer budget between two lines","tags":["Budgets"]}},"/api/budgets/{budgetId}/export":{"get":{"description":"One sheet, **Budget**: the lines grouped by cost centre (by code; lines with none last, as \"Unallocated\"), each group with a subtotal, then the budget total.\n\nColumns: Code (BOQ item code), Description, Bill item, Authorized, Variations, Revised, Committed, Requested, Actual incurred, Forecast, Variance. **Committed** sums purchase-order lines drawn against the line for `ISSUED` and `CLOSED` orders; **Requested** is the line listing’s `exposure.requestedAmount`. Totals are summed exactly.\n\nNeeds only `budget.view`. Named `TetraBuild_{ProjectCode}_{BudgetCode}_Budget.xlsx`.","operationId":"export","parameters":[{"name":"budgetId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such budget in your organization.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Export a budget (.xlsx)","tags":["Budgets"]}},"/api/projects/{projectId}/budgets":{"get":{"description":"A project may hold several budgets — an original and its revisions, or a separate contingency budget — but **at most one is `ACTIVE`**, and that is the one authorizing spending. This is a paginated collection: filter by `status`, page with `page` and `limit`.\n\nEach budget carries `totalAmount` and `lineCount`, gathered for the whole page in one aggregate query rather than one per row. Totals are always derived from the lines and never stored.\n\nOrdered by `budgetCode`. A project in another organization returns `404`, identically to one that does not exist.","operationId":"list","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","ACTIVE","CLOSED"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the project’s budgets.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BudgetDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s budgets","tags":["Budgets"]},"post":{"description":"The budget is created as `DRAFT`. It becomes financially authoritative only through `PATCH /budgets/{budgetId}/status`, which validates the transition and enforces one `ACTIVE` budget per project — an ordinary PATCH cannot activate a budget.\n\n`budgetCode` is normalised to upper case and must be unique within the project; a duplicate returns `409`. It is immutable thereafter.\n\n**Lines may be supplied with the header**, in which case everything commits in one transaction or nothing does — a budget is financial information, so a header that survived while half its lines failed would be a partial authorization that looks complete. Each line’s BOQ item must belong to this project and sit in an `ACTIVE` bill.\n\n`organizationId` and `projectId` are never accepted in the body: tenancy comes from the session and the project from the path, so a client cannot create a cross-tenant budget. A `COMPLETED` or `CANCELLED` project accepts no new budget (`409`).","operationId":"create","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBudgetDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, or a supplied BOQ item or cost centre is not usable from this project."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Duplicate `budgetCode` on this project, a terminal project, or a supplied BOQ item’s bill is not `ACTIVE`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create a budget for a project","tags":["Budgets"]}},"/api/requisitions/{requisitionId}":{"get":{"description":"`totalEstimatedAmount` is the sum of the lines’ estimated amounts and `lineCount` the number of lines, both computed by the database on every read. Neither is stored: a persisted total is a second source of truth that disagrees with its own lines the first time one is written outside the service.\n\nAn empty requisition reports `\"0.0000\"`, not `\"0\"` — the scale is uniform so a client parsing decimal strings never special-cases zero.\n\nThe figure is an **estimate at 4 decimal places**, deliberately not money: the real price is discovered by procurement in a later stage.\n\nA requisition in another organization returns `404`, identically to one that does not exist: a `403` would confirm it exists and disclose the platform’s client list.","operationId":"findOne","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a requisition with its derived totals","tags":["Requisitions"]},"patch":{"description":"`requisitionNumber`, `requestedByMembershipId` and `status` are all rejected with `400`. The number is immutable once set, the requester is who raised the request rather than an editable attribute, and the status moves only through `PATCH /requisitions/{id}/status` — which is what makes the transition rules unbypassable.\n\n**Editable until approved.** An `APPROVED` or `CANCELLED` requisition returns `409` and stays fully readable.\n\n**Who edits decides how the edit lands.** When the requisition is `SUBMITTED` and it is the caller’s turn to approve it, the edit lands **in place**: the approval stays at their step, earlier decisions stand, and they can approve straight after. The approvers cannot be changed this way (`409 APPROVER_ROUTE_FIXED`), nor can the last line be removed (`409 REQUISITION_WOULD_BE_EMPTY`). Anybody else’s edit to a `SUBMITTED` or `REJECTED` requisition reopens it to `DRAFT` and supersedes any pending approval, so it must be submitted again to re-route it from step 1.\n\nSend `approverEdit=true` to insist on the in-place behaviour: an edit that would reopen the request is then refused with `409 APPROVAL_TURN_CHANGED` and nothing is written.\n\nEvery edit that changes something stamps `lastModifiedBy*`/`lastModifiedAt` and records a `requisition_updated` audit event with the fields changed.\n\nEditing on a `COMPLETED` or `CANCELLED` project is permitted: correcting a delivered project’s records is legitimate, even though raising new demand on it is not.","operationId":"update","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"approverEdit","required":false,"in":"query","description":"Edit as the current approver. Refused with `409 APPROVAL_TURN_CHANGED` if the requisition is not waiting on the caller, rather than reopening it.","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRequisitionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, or an immutable field (`requisitionNumber`, `requestedByMembershipId`, `status`) was sent."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The requisition is `APPROVED` or `CANCELLED`; or, editing in place, the approvers were changed or the request is no longer waiting on the caller; or `STALE_WRITE`: `expectedUpdatedAt` was sent and the requisition has been saved since.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a requisition that is not yet approved","tags":["Requisitions"]}},"/api/requisitions/{requisitionId}/status":{"patch":{"description":"`DRAFT → SUBMITTED, CANCELLED`; `SUBMITTED → CANCELLED`; `CANCELLED` is terminal. Anything else returns `409` naming the legal moves. Setting the current status again succeeds unchanged, so retrying a request that already applied does not fail.\n\n**Submitting locks the requisition**: neither the header nor any line may change afterwards, and lines can no longer be added or removed. That is what makes the request auditable — what was submitted is what is on file.\n\n**A cancelled requisition is never reopened.** The request that was raised is exactly what an audit needs to find; raising the need again means raising a new requisition, which is honest about there having been two.\n\nGuarded by `requisition.submit` rather than `requisition.update`, because deciding a request’s fate is a different authority from drafting it — a site clerk routinely drafts what a project manager submits.\n\nConcurrency-safe by conditional UPDATE, not by a prior read: two simultaneous submissions cannot both apply, and the loser is told what the requisition actually became.\n\nPermitted even on a terminal project, so a finished job never leaves requests that can never be submitted or withdrawn.\n\nOnly `SUBMITTED` requisitions count toward a budget line’s reported exposure — see `GET /budgets/{budgetId}/lines`.","operationId":"changeStatus","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeRequisitionStatusDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Illegal transition, or the requisition is terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Submit or cancel a requisition","tags":["Requisitions"]}},"/api/requisitions/{requisitionId}/actual-expenditure":{"get":{"description":"Each line’s approved estimate beside its recorded actual and the signed variance (`actual - estimate`), plus the totals. Every figure is computed by PostgreSQL at 4 decimal places. `actualAmount` is `null` until recorded, and `\"0.0000\"` is a recorded zero.\n\n`procured` marks a line on a live purchase order: its supplier invoice carries its cost, so an actual cannot be recorded here.\n\nRequires `requisition.record_actual` — held by Administrator and Approver by default, not by requesters.","operationId":"getActuals","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionActualsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get the actual amount incurred on a requisition","tags":["Requisitions"]},"put":{"description":"Sets each named line’s actual amount — an absolute figure, never an increment, so correcting 8,500 to 9,000 stores 9,000 and repeating a request changes nothing. `null` clears a figure recorded in error. Lines left out keep what they have.\n\n**Feeds the budget line.** Each recorded amount reaches its line’s budget line as `requisitionActualAmount` and inside `totalActualAmount` on `GET /budgets/{budgetId}/lines`, at once and exactly once. The estimate, the approval and the budget are never changed, and `actualIncurredAmount` stays as Finance entered it.\n\nRefused with `409` unless the requisition is `APPROVED`, and for a line with no budget line or on a live purchase order (`REQUISITION_LINE_PROCURED`) — that cost arrives through the supplier invoice. One refused line refuses the whole request.\n\nAmounts are decimal **strings** with at most 14 integer and 4 decimal digits; a negative value or a JSON number is a `400`. Every change records a `requisition_actual_recorded` audit event with each line’s previous and new figure.","operationId":"recordActuals","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordRequisitionActualsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionActualsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, a line is named twice, or a line is not on this requisition."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The requisition is not `APPROVED`, or a line has no budget line or is on a live purchase order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Record the actual amount incurred on an approved requisition","tags":["Requisitions"]}},"/api/requisitions/{requisitionId}/lines":{"get":{"description":"Always paginated. Filter with `budgetLineId`.\n\nOrdered by `sortOrder`, then `id`. Ending on a unique column makes the order **total**, which is what keeps pagination safe: rows tied on `sortOrder` could otherwise swap between pages and be served twice or skipped.\n\nEach line carries its budget line’s description and authorized amount, plus the **BOQ item id and code inherited through that budget line**. The BOQ reference is not stored on the line — it is read from the budget line, so the two can never disagree. `boqItemId` is null where the budget line authorizes something the bill does not measure, such as overheads or contingency.","operationId":"listLines","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"budgetLineId","required":false,"in":"query","description":"Restrict to lines drawing against one budget line, or pass `unassigned`\nfor the lines still awaiting one.","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the requisition’s lines.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RequisitionLineDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a requisition’s lines","tags":["Requisitions"]},"post":{"description":"`requisition.update`, not `requisition.create`: adding a line modifies the requisition.\n\n`budgetLineId` is **optional and normally omitted**: the approver assigns each line to a budget line when they approve, and the final approval is refused while any line is unassigned. Only a caller holding `budget.view` may set it here (`403` otherwise). When set, the budget line must belong to the **same project** as this requisition and to your organization (`400` otherwise, with one message for all three cases so the response never confirms another tenant’s records exist), and its budget must be `ACTIVE` (`409` otherwise). Both rules are also held by composite foreign keys.\n\n`estimatedAmount` is **computed by PostgreSQL** as `quantity × estimatedUnitCost` and is rejected with `400` if sent. `quantity` and `estimatedUnitCost` are decimal **strings**, never JSON numbers: a number has already lost exactness before the server sees it. At most 14 integer and 4 decimal digits, so an oversized value is a `400` rather than a `500`. Zero is accepted on a draft; negative is not.\n\nAllowed until the requisition is approved; refused with `409` once it is `APPROVED` or `CANCELLED`.\n\n**Who edits decides how the edit lands.** When the requisition is `SUBMITTED` and it is the caller’s turn to approve it, the edit lands **in place**: the approval stays at their step, earlier decisions stand, and they can approve straight after. The approvers cannot be changed this way (`409 APPROVER_ROUTE_FIXED`), nor can the last line be removed (`409 REQUISITION_WOULD_BE_EMPTY`). Anybody else’s edit to a `SUBMITTED` or `REJECTED` requisition reopens it to `DRAFT` and supersedes any pending approval, so it must be submitted again to re-route it from step 1.\n\nSend `approverEdit=true` to insist on the in-place behaviour: an edit that would reopen the request is then refused with `409 APPROVAL_TURN_CHANGED` and nothing is written.\n\nEvery edit that changes something stamps `lastModifiedBy*`/`lastModifiedAt` and records a `requisition_updated` audit event with the fields changed.","operationId":"createLine","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"approverEdit","required":false,"in":"query","description":"Edit as the current approver. Refused with `409 APPROVAL_TURN_CHANGED` if the requisition is not waiting on the caller, rather than reopening it.","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRequisitionLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, `estimatedAmount` was sent, or the budget line is not usable from this requisition’s project."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The requisition is locked, the project is terminal, or the budget is not `ACTIVE`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a line to a requisition that is not yet approved","tags":["Requisitions"]}},"/api/requisitions/{requisitionId}/lines/{lineId}":{"patch":{"description":"`budgetLineId` is rejected with `400`. Which budget line a request draws against is assigned by an approver at approval (`POST /requisitions/{id}/approval/approve`), and an edit keeps whatever they assigned.\n\nChanging `quantity` or `estimatedUnitCost` makes PostgreSQL recompute `estimatedAmount`.\n\nAllowed until the requisition is approved; refused with `409` once it is `APPROVED` or `CANCELLED`.\n\n**Who edits decides how the edit lands.** When the requisition is `SUBMITTED` and it is the caller’s turn to approve it, the edit lands **in place**: the approval stays at their step, earlier decisions stand, and they can approve straight after. The approvers cannot be changed this way (`409 APPROVER_ROUTE_FIXED`), nor can the last line be removed (`409 REQUISITION_WOULD_BE_EMPTY`). Anybody else’s edit to a `SUBMITTED` or `REJECTED` requisition reopens it to `DRAFT` and supersedes any pending approval, so it must be submitted again to re-route it from step 1.\n\nSend `approverEdit=true` to insist on the in-place behaviour: an edit that would reopen the request is then refused with `409 APPROVAL_TURN_CHANGED` and nothing is written.\n\nEvery edit that changes something stamps `lastModifiedBy*`/`lastModifiedAt` and records a `requisition_updated` audit event with the fields changed.","operationId":"updateLine","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"approverEdit","required":false,"in":"query","description":"Edit as the current approver. Refused with `409 APPROVAL_TURN_CHANGED` if the requisition is not waiting on the caller, rather than reopening it.","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRequisitionLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, or `budgetLineId`/`estimatedAmount` was sent."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The requisition is `APPROVED` or `CANCELLED` and can no longer be modified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a requisition line","tags":["Requisitions"]},"delete":{"description":"Allowed until the requisition is approved; `APPROVED` or `CANCELLED` returns `409`.\n\n**Who edits decides how the edit lands.** When the requisition is `SUBMITTED` and it is the caller’s turn to approve it, the edit lands **in place**: the approval stays at their step, earlier decisions stand, and they can approve straight after. The approvers cannot be changed this way (`409 APPROVER_ROUTE_FIXED`), nor can the last line be removed (`409 REQUISITION_WOULD_BE_EMPTY`). Anybody else’s edit to a `SUBMITTED` or `REJECTED` requisition reopens it to `DRAFT` and supersedes any pending approval, so it must be submitted again to re-route it from step 1.\n\nSend `approverEdit=true` to insist on the in-place behaviour: an edit that would reopen the request is then refused with `409 APPROVAL_TURN_CHANGED` and nothing is written.\n\nEvery edit that changes something stamps `lastModifiedBy*`/`lastModifiedAt` and records a `requisition_updated` audit event with the fields changed.\n\nThis is the only destructive operation in the API, and deliberately narrow: a mistyped line on a request nobody has seen has no history worth keeping, whereas an `OMITTED` status would raise \"does it still count toward the total?\" for no benefit.\n\nThere is **no delete for a requisition itself** — `CANCELLED` is the retirement path, so the request that was raised stays traceable.","operationId":"removeLine","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"approverEdit","required":false,"in":"query","description":"Edit as the current approver. Refused with `409 APPROVAL_TURN_CHANGED` if the requisition is not waiting on the caller, rather than reopening it.","schema":{"type":"boolean"}}],"responses":{"204":{"description":"The line was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The requisition is `APPROVED` or `CANCELLED`; its lines are locked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from a requisition","tags":["Requisitions"]}},"/api/requisitions/{requisitionId}/attachments":{"post":{"operationId":"attachToRequisition","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"caption":{"type":"string"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Attach a supporting file to a requisition","tags":["Requisitions"]},"get":{"operationId":"listRequisitionAttachments","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a requisition’s attachments","tags":["Requisitions"]}},"/api/requisitions/{requisitionId}/attachments/{attachmentId}":{"delete":{"description":"Requires `requisition.attachment_delete`, held by Administrator alone by default: a supporting document is evidence an approval rests on. Uploading needs only `requisition.update`.","operationId":"removeRequisitionAttachment","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"attachmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The attachment was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition or attachment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a requisition’s attachment","tags":["Requisitions"]}},"/api/requisitions/{requisitionId}/lines/{lineId}/attachments":{"post":{"operationId":"attachToLine","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"caption":{"type":"string"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Attach a supporting file to a requisition line","tags":["Requisitions"]},"get":{"operationId":"listLineAttachments","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a requisition line’s attachments","tags":["Requisitions"]}},"/api/requisitions/{requisitionId}/lines/{lineId}/attachments/{attachmentId}":{"delete":{"description":"Requires `requisition.attachment_delete`, held by Administrator alone by default: a supporting document is evidence an approval rests on. Uploading needs only `requisition.update`.","operationId":"removeLineAttachment","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"attachmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The attachment was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition, line or attachment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a requisition line’s attachment","tags":["Requisitions"]}},"/api/requisitions":{"get":{"description":"The cross-project register: every requisition in the organization, newest first, however many projects they span. Filter by `projectId`, `status`, `requisitionTypeId` or `requestedByMembershipId`; page with `page` and `limit`.\n\nEach row carries `projectName` and `projectCode`. Not decoration here — `requisitionNumber` restarts at `REQ-0001` in every project, so a number alone does not identify a request once a list spans them.\n\nScoped to the caller’s organization like every other read, with no way to widen it. Identical page shape, filters and ordering to the project-scoped listing below, because both are one service method.\n\nFiltering by a `projectId` in another organization returns `404`, identically to one that does not exist — an empty page would confirm the project is real but withheld.\n\nA caller holding `requisition.view_own` without `requisition.view` sees only the requisitions they raised: `requestedByMembershipId` is forced to their own membership, and any value they send is ignored.","operationId":"listAll","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","SUBMITTED","CANCELLED","APPROVED","REJECTED"]}},{"name":"requisitionTypeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"requestedByMembershipId","required":false,"in":"query","description":"Restrict to requests raised by one membership.","schema":{"format":"uuid","type":"string"}},{"name":"projectId","required":false,"in":"query","description":"Narrow the **cross-project** register to one project.\n\nIgnored by `GET /projects/{projectId}/requisitions`, which takes its\nproject from the path — a query parameter that could contradict the path\nwould be a way to ask one project's route for another project's rows.","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Free-text match on the requisition number or its purpose.\n\nApplied by the DATABASE, not the client. A register that filters the page\nit happens to hold would miss every match on page two while reporting a\ntotal for the whole set — the search would simply appear broken.","schema":{"maxLength":200,"type":"string"}},{"name":"procurable","required":false,"in":"query","description":"`true` keeps only requisitions Procurement works on: those with at least\none line that is not paid directly, or with no lines at all (a vehicle\nrequest). Procurement → Approved requisitions, the order form's picker and\nthe RFQ form send it. Matches everything until a type is routed to Pay\ndirectly.","schema":{"type":"string","enum":["true","false"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the organization’s requisitions.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RequisitionDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization, when `projectId` is given.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List requisitions across the organization","tags":["Requisitions"]}},"/api/requisition-summary":{"get":{"description":"What the register’s summary tiles report: how many requisitions exist, what they are estimated to be worth, how many await a decision and across how many projects.\n\nTakes the same filters as the listing (`projectId`, `status`, `requisitionTypeId`, `requestedByMembershipId`) and covers **every matching requisition, not one page**. A client summing the rows it holds would state the page’s value under an organization-wide label.\n\nAmounts are decimal strings summed by PostgreSQL from the requisition lines — the same derivation `totalEstimatedAmount` uses on a single requisition, so the figures cannot disagree.\n\nA caller holding `requisition.view_own` without `requisition.view` sees only the requisitions they raised: `requestedByMembershipId` is forced to their own membership, and any value they send is ignored.","operationId":"summary","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","SUBMITTED","CANCELLED","APPROVED","REJECTED"]}},{"name":"requisitionTypeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"requestedByMembershipId","required":false,"in":"query","description":"Restrict to requests raised by one membership.","schema":{"format":"uuid","type":"string"}},{"name":"projectId","required":false,"in":"query","description":"Narrow the **cross-project** register to one project.\n\nIgnored by `GET /projects/{projectId}/requisitions`, which takes its\nproject from the path — a query parameter that could contradict the path\nwould be a way to ask one project's route for another project's rows.","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Free-text match on the requisition number or its purpose.\n\nApplied by the DATABASE, not the client. A register that filters the page\nit happens to hold would miss every match on page two while reporting a\ntotal for the whole set — the search would simply appear broken.","schema":{"maxLength":200,"type":"string"}},{"name":"procurable","required":false,"in":"query","description":"`true` keeps only requisitions Procurement works on: those with at least\none line that is not paid directly, or with no lines at all (a vehicle\nrequest). Procurement → Approved requisitions, the order form's picker and\nthe RFQ form send it. Matches everything until a type is routed to Pay\ndirectly.","schema":{"type":"string","enum":["true","false"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionSummaryDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization, when `projectId` is given.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Headline figures for the requisitions register","tags":["Requisitions"]}},"/api/requisition-requesters":{"get":{"description":"What the register’s **Requested by** filter offers: everyone in your organization who has raised at least one requisition, with how many, sorted by name. Pass an entry’s `membershipId` as `requestedByMembershipId` to the listing and its summary.\n\nDrawn from the requisitions, not the staff directory, so it needs only the register’s own read permission — not `staff.view` — and never offers someone who could only filter to an empty page.\n\nNot paginated: it is bounded by headcount. Narrow it with `projectId`; a `projectId` in another organization returns `404`, identically to one that does not exist.\n\nA caller holding `requisition.view_own` without `requisition.view` gets only themself, and only once they have raised something.","operationId":"requesters","parameters":[{"name":"projectId","required":false,"in":"query","description":"Only people who raised a requisition on this project. Omitted, it spans every project in your organization.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RequisitionRequesterDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization, when `projectId` is given.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"People who have raised requisitions","tags":["Requisitions"]}},"/api/requisition-export":{"get":{"description":"The project expenditure report (`GET /projects/{projectId}/requisitions/export`) across **every project in your organization**, for the cross-project register.\n\nSame sections, totals, status default, approval-date rules and one-sheet-per-currency split as the project export, plus a **Project** column (the project code) after Date, since a section then mixes requisitions from several projects.\n\nGiven `projectId`, it is exactly that project’s export — same workbook and filename. A `projectId` in another organization returns `404`, identically to one that does not exist.","operationId":"exportAll","parameters":[{"name":"status","required":false,"in":"query","description":"Requisition statuses to include. Repeat the parameter for several (`?status=SUBMITTED&status=APPROVED`). Defaults to `APPROVED`: authorised spend.","schema":{"minItems":1,"type":"array","items":{"type":"string","enum":["DRAFT","SUBMITTED","CANCELLED","APPROVED","REJECTED"]}}},{"name":"requisitionTypeId","required":false,"in":"query","description":"Restrict the report to one requisition type (one section).","schema":{"format":"uuid","type":"string"}},{"name":"dateFrom","required":false,"in":"query","description":"Earliest **approval date** to include, inclusive (`YYYY-MM-DD`, in the organization’s timezone). Only valid when every requested status is `APPROVED`, since other requisitions have no approval date.","schema":{"example":"2026-06-01","type":"string"}},{"name":"dateTo","required":false,"in":"query","description":"Latest **approval date** to include, inclusive (`YYYY-MM-DD`). Same restriction as `dateFrom`.","schema":{"example":"2026-09-30","type":"string"}},{"name":"projectId","required":false,"in":"query","description":"Restrict the report to one project. Omitted, it spans every project in your organization.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"The workbook, as an attachment named `TetraBuild_{OrganizationName}_Requisition_Expenditure_Report.xlsx` (or the project export’s name when `projectId` is given).","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, `dateFrom` is after `dateTo`, or a date filter was combined with a status other than `APPROVED`."},"401":{"description":"Missing or invalid bearer token.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization, when `projectId` is given.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Export the organization’s requisitions as an expenditure report (.xlsx)","tags":["Requisitions"]}},"/api/projects/{projectId}/requisitions":{"get":{"description":"A paginated work queue, newest first. Filter by `status`, `requisitionTypeId` or `requestedByMembershipId`; page with `page` and `limit`.\n\nEach requisition carries `totalEstimatedAmount` and `lineCount`, gathered for the whole page in one aggregate query rather than one per row, plus the requester’s name joined in. Totals are always derived from the lines and never stored.\n\n`totalEstimatedAmount` is an **estimate**, not a commitment and not a cost. A requisition requests; it does not approve, commit or spend.\n\nA project in another organization returns `404`, identically to one that does not exist.\n\nA caller holding `requisition.view_own` without `requisition.view` sees only the requisitions they raised: `requestedByMembershipId` is forced to their own membership, and any value they send is ignored.","operationId":"list","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","SUBMITTED","CANCELLED","APPROVED","REJECTED"]}},{"name":"requisitionTypeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"requestedByMembershipId","required":false,"in":"query","description":"Restrict to requests raised by one membership.","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Free-text match on the requisition number or its purpose.\n\nApplied by the DATABASE, not the client. A register that filters the page\nit happens to hold would miss every match on page two while reporting a\ntotal for the whole set — the search would simply appear broken.","schema":{"maxLength":200,"type":"string"}},{"name":"procurable","required":false,"in":"query","description":"`true` keeps only requisitions Procurement works on: those with at least\none line that is not paid directly, or with no lines at all (a vehicle\nrequest). Procurement → Approved requisitions, the order form's picker and\nthe RFQ form send it. Matches everything until a type is routed to Pay\ndirectly.","schema":{"type":"string","enum":["true","false"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the project’s requisitions.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RequisitionDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s requisitions","tags":["Requisitions"]},"post":{"description":"Creates the requisition as `DRAFT` with a server-generated `requisitionNumber` (`REQ-0001`), sequential within the project. The number is race-safe: concurrent requests serialise on an advisory lock and a unique constraint is the guarantee, so two callers never receive the same number.\n\nThe **requester is derived from your session** — the membership you hold in this organization. `requestedByMembershipId` is not accepted in the body, so a request cannot be raised in somebody else’s name. A platform administrator acting outside their own organization has no membership to record and receives `409`: a financial request needs an accountable requester.\n\n**Lines may be supplied with the header**, in which case the header, its number and every line commit in one transaction or none do. Lines normally carry no budget line — the approver assigns them at approval. Only a caller holding `budget.view` may name one (`403` otherwise), and it must belong to this project with an `ACTIVE` budget.\n\n**`vehicleDetail` replaces `lines`** when the requisition type's `category` is `VEHICLE`: it is required and `lines` is refused. For a `GENERAL` type the reverse holds — `vehicleDetail` is refused.\n\nIt becomes real only through `PATCH /requisitions/{id}/status`, which also locks it — an ordinary PATCH cannot submit.\n\n`organizationId`, `projectId`, `requisitionNumber`, `status` and `estimatedAmount` are never accepted in the body. A `COMPLETED` or `CANCELLED` project accepts no new requisition (`409`).","operationId":"create","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRequisitionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, a supplied budget line is not usable from this project, or `vehicleDetail`/`lines` was sent for the wrong requisition type category."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The project is terminal, you hold no membership of this organization, or a supplied budget line’s budget is not `ACTIVE`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Raise a requisition for a project","tags":["Requisitions"]}},"/api/projects/{projectId}/requisitions/export":{"get":{"description":"Downloads an Excel workbook of the project’s requisition lines, one row per line, grouped into **one section per requisition type** — whatever types your organization has configured, ordered by type code. Each section ends in a subtotal and the sheet in a grand total; both are exact sums of the exported line amounts.\n\n**Columns:** No. (restarting per section), Date (the **approval date**, in the organization’s timezone), Details (line description), Requested By (the requester’s full name), Unit, Qty, Unit Cost and Total Cost (line estimates).\n\n**Statuses:** `APPROVED` only unless `status` says otherwise — authorised spend, not requests. `dateFrom`/`dateTo` filter the approval date and are therefore refused (`400`) alongside any other status.\n\n**Currency:** the requisition’s, else the project’s. A project that mixes currencies gets one worksheet per currency; amounts in different currencies are never added together.\n\nThe complete filtered set, not a page. Requires the same `requisition.view` the listing does — the workbook shows nothing the register does not. A project in another organization returns `404`.","operationId":"export","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","description":"Requisition statuses to include. Repeat the parameter for several (`?status=SUBMITTED&status=APPROVED`). Defaults to `APPROVED`: authorised spend.","schema":{"minItems":1,"type":"array","items":{"type":"string","enum":["DRAFT","SUBMITTED","CANCELLED","APPROVED","REJECTED"]}}},{"name":"requisitionTypeId","required":false,"in":"query","description":"Restrict the report to one requisition type (one section).","schema":{"format":"uuid","type":"string"}},{"name":"dateFrom","required":false,"in":"query","description":"Earliest **approval date** to include, inclusive (`YYYY-MM-DD`, in the organization’s timezone). Only valid when every requested status is `APPROVED`, since other requisitions have no approval date.","schema":{"example":"2026-06-01","type":"string"}},{"name":"dateTo","required":false,"in":"query","description":"Latest **approval date** to include, inclusive (`YYYY-MM-DD`). Same restriction as `dateFrom`.","schema":{"example":"2026-09-30","type":"string"}}],"responses":{"200":{"description":"The workbook, as an attachment named `TetraBuild_{ProjectCode}_{ProjectName}_Requisition_Expenditure_Report.xlsx`.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, `dateFrom` is after `dateTo`, or a date filter was combined with a status other than `APPROVED`."},"401":{"description":"Missing or invalid bearer token.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Export a project’s requisitions as an expenditure report (.xlsx)","tags":["Requisitions"]}},"/api/approval-policies":{"get":{"description":"A page of this organization’s approval policies, newest first. At most one is ACTIVE at a time; the others are drafts being prepared or closed revisions kept for provenance.","operationId":"findAll","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","ACTIVE","CLOSED"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalPolicyDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List approval policies","tags":["Approval Policies"]},"post":{"description":"Creates a DRAFT policy, optionally with its steps, in one transaction. A policy authorizes nothing until it is activated, and activation refuses a ladder whose value bands leave a gap.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApprovalPolicyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalPolicyDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A policy with this name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create an approval policy","tags":["Approval Policies"]}},"/api/approval-policies/{policyId}":{"get":{"description":"The policy and its ladder, in step order. Each step names a role and the inclusive value band it may authorize; a step with no maximum is the authority of last resort.","operationId":"findOne","parameters":[{"name":"policyId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalPolicyDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such approval policy in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get an approval policy with its steps","tags":["Approval Policies"]},"patch":{"description":"Changes the policy’s own fields. Permitted only while DRAFT: editing rules that are currently routing requests would change who may approve work already in flight. `status` is absent from this DTO — use the status route.","operationId":"update","parameters":[{"name":"policyId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApprovalPolicyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalPolicyDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such approval policy in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The policy is ACTIVE or CLOSED, or the name is taken.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft approval policy","tags":["Approval Policies"]}},"/api/approval-policies/{policyId}/status":{"patch":{"description":"DRAFT → ACTIVE | CLOSED, ACTIVE → CLOSED; CLOSED is terminal. At most one policy may be ACTIVE per organization, so close the current one before activating its replacement — which is how a revision works without any versioning machinery. Activation refuses a policy with no steps, or whose bands leave some total unroutable.","operationId":"changeStatus","parameters":[{"name":"policyId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeApprovalPolicyStatusDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalPolicyDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such approval policy in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Illegal transition, another policy is already ACTIVE, or the ladder leaves a gap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Activate or close an approval policy","tags":["Approval Policies"]}},"/api/approval-policies/{policyId}/steps":{"post":{"description":"Adds one rung to the ladder: a role, and the inclusive value band its holders may authorize. Bands may overlap — that is how a firm says a large request needs two signatures — but must leave no gap, which activation checks.","operationId":"addStep","parameters":[{"name":"policyId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApprovalPolicyStepDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalPolicyStepDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such approval policy in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The policy is ACTIVE or CLOSED, or the step number is taken.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a step to a draft approval policy","tags":["Approval Policies"]}},"/api/approval-policies/{policyId}/steps/{stepId}":{"delete":{"description":"Permitted only while DRAFT. Requisitions already submitted are unaffected regardless — they carry their own frozen copy of the route — but allowing the edit on a live policy would change the route for later requests with nothing recording the change.","operationId":"removeStep","parameters":[{"name":"policyId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"stepId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The step was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such policy or step in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The policy is ACTIVE or CLOSED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a step from a draft approval policy","tags":["Approval Policies"]}},"/api/approvers":{"get":{"description":"Active members holding `approval.decide`, with the roles they hold, ordered by name. The caller is excluded — nobody may approve their own request, so offering themselves only to refuse it at submission would be a worse way to say so. Naming somebody absent from this list is refused when the requisition is submitted.","operationId":"listApprovers","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EligibleApproverDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List people who can be named to approve a requisition","tags":["Approvals"]}},"/api/approvals/pending":{"get":{"description":"The approver’s inbox: pending requisitions whose current step either names a role the caller holds or names the caller personally, oldest first — an approval queue is work, and the request waiting longest is the one somebody is chasing. The caller’s own requests are excluded, since nobody may decide their own.","operationId":"findPending","parameters":[{"name":"projectId","required":false,"in":"query","description":"Narrow the queue to one project.","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List approvals awaiting this user","tags":["Approvals"]}},"/api/requisitions/{requisitionId}/approval":{"get":{"description":"The instance, the frozen route it must follow, and every decision taken — read as a timeline, where a step with no decision is one still awaiting it. The route is the copy taken at submission, so it reflects the rules as they stood then even if the policy has since changed.","operationId":"findOne","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization, or it has no approval workflow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a requisition’s approval workflow","tags":["Approvals"]}},"/api/requisitions/{requisitionId}/approval/requisition":{"get":{"description":"The same record as `GET /requisitions/{id}`, reachable by an approver who holds `approval.view` and appears on this requisition’s frozen route — without granting them `requisition.view`, which is organization-wide and would let them read every requisition in the firm.\n\nAny step on the route qualifies, not only the current one: an approver who has already signed may look back at what they authorized, and one waiting at a later step may read ahead.\n\nA caller who is not on the route gets `404`, identically to a requisition that does not exist — a `403` would confirm it exists.","operationId":"findRoutedRequisition","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequisitionDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization, or you are not on its approval route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Read a requisition you are named to approve","tags":["Approvals"]}},"/api/requisitions/{requisitionId}/approval/lines":{"get":{"description":"The same lines as `GET /requisitions/{id}/lines`, under the approver’s own permission. **This is what an approver is actually authorizing** — a decision taken against a total with no sight of the items behind it is not a review.\n\nScoped identically to the route above: on the approval route, at any step, or `404`.","operationId":"findRoutedLines","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"budgetLineId","required":false,"in":"query","description":"Restrict to lines drawing against one budget line, or pass `unassigned`\nfor the lines still awaiting one.","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the requisition’s lines.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RequisitionLineDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization, or you are not on its approval route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Read the lines of a requisition you are named to approve","tags":["Approvals"]}},"/api/requisitions/{requisitionId}/approval/budget-lines":{"get":{"description":"Every line of the project’s `ACTIVE` budgets, with its revised amount and what SUBMITTED and APPROVED requisitions have already requested against it — the balance an approver weighs when choosing where a request’s money comes from.\n\n**Only the approver the requisition is waiting on now** may read this, under their approval authority rather than `budget.view`: the requester never sees the budget, and neither does an approver whose turn has not come or has passed. Anybody else gets the same `403` a decision would.\n\nUnpaginated, because hiding the right line on another page invites choosing a wrong one. The remainder may be negative; nothing here blocks an over-request.","operationId":"findAssignableBudgetLines","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalBudgetLineDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization, or it has no approval workflow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The approval has already been decided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Budget lines the current approver may assign this requisition to","tags":["Approvals"]}},"/api/requisitions/{requisitionId}/approval/approve":{"post":{"description":"Records an immutable approval and advances the workflow — or authorizes the request outright if this was the last required step. Requires both the `approval.decide` permission and the role the current step names. The requester may never approve their own request. Approving over budget is permitted: the remaining budget at decision time is recorded against the decision, so the overrun is visible rather than hidden.\n\n**`lineAssignments` places the requisition’s lines against budget lines** — see `GET /requisitions/{id}/approval/budget-lines` for the choices. Any approver may assign or change lines at their step; lines left out keep what they have. Each budget line must be on this project with an `ACTIVE` budget (`400` / `409`). **The final approval is refused with `409 BUDGET_LINES_UNASSIGNED` while any line has none**, and the whole decision rolls back. The recorded remaining budget is taken after the assignments.\n\nThe final approval emails the requester that their requisition is approved, naming who approved it and any comment, and no budget line. Earlier steps email only the next approver.","operationId":"approve","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveRequisitionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nValidation failed, a line is not on this requisition, a line is assigned twice, or a budget line is not on this project."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization, or it has no approval workflow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Already decided, the step is taken, the requisition is no longer SUBMITTED, the caller has no membership, a budget is not `ACTIVE`, or this is the final approval and a line has no budget line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Approve a requisition at the current step","tags":["Approvals"]}},"/api/requisitions/{requisitionId}/approval/reject":{"post":{"description":"Records an immutable rejection and settles the workflow. **Rejection is terminal**: the requisition becomes REJECTED and is never reopened, because the request that was refused is what an audit needs to find. Correcting the need means raising a new requisition, which is honest about there having been two. A reason is required, and the requester is emailed it.","operationId":"reject","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideApprovalDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization, or it has no approval workflow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Already decided, the step is taken, the requisition is no longer SUBMITTED, or the caller has no membership.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Reject a requisition","tags":["Approvals"]}},"/api/requisitions/{requisitionId}/approval/override-reject":{"post":{"description":"Rejects a SUBMITTED requisition at whatever step it is waiting on, without being that step’s approver. Requires `approval.override`; no step authority is consulted. The rejection is recorded against the current step with `isOverride: true`, so the history shows the administrator, never the approver it was waiting on. It settles the workflow exactly like an approver’s rejection: terminal, a reason is required, and the requester is emailed it. The approver it was waiting on is emailed too, when the step names a person.\n\nThe requester may override-reject their own request: refusing it authorizes nothing. Override never approves.","operationId":"overrideReject","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideApprovalDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization, or it has no approval workflow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Already decided, the step was decided a moment earlier, the requisition is no longer SUBMITTED, or the caller has no membership in this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Reject a submitted requisition as an administrator","tags":["Approvals"]}},"/api/projects/{projectId}/audit-events":{"get":{"description":"A paginated, immutable register of business events on the project — BOQ ratification, requisition submission and approval decisions, purchase order actions, goods receipt posting, and project membership changes. Newest first.\n\nFilter by `category`, `action`, `actorMembershipId`, or an `occurredAt` range with `dateFrom`/`dateTo`.\n\nA project in another organization returns `404`, identically to one that does not exist.","operationId":"list","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"category","required":false,"in":"query","schema":{"type":"string","enum":["boq_management","budget_management","requisitions","procurement","inventory","access_control","project_lifecycle"]}},{"name":"action","required":false,"in":"query","schema":{"type":"string","enum":["boq_ratified","boq_imported","boq_item_deleted","budget_transferred","requisition_submitted","requisition_approved","requisition_rejected","requisition_cancelled","requisition_budget_line_assigned","requisition_updated","requisition_actual_recorded","purchase_order_issued","purchase_order_cancelled","purchase_order_closed","goods_receipt_posted","material_issue_posted","material_issue_cancelled","stock_transfer_dispatched","stock_transfer_received","stock_transfer_cancelled","material_return_posted","material_return_cancelled","supplier_return_posted","supplier_return_cancelled","supplier_invoice_submitted","supplier_invoice_approved","supplier_invoice_held","supplier_invoice_released","supplier_invoice_cancelled","supplier_payment_posted","supplier_payment_voided","rfq_issued","rfq_awarded","rfq_cancelled","subcontract_activated","subcontract_variation_approved","subcontract_valuation_certified","subcontract_practically_complete","subcontract_final_account_closed","subcontract_terminated","inventory_adjustment_approved","inventory_adjustment_rejected","stock_count_posted","project_member_added","project_member_status_changed","stock_count_sent_to_finance","stock_count_returned_for_recount","project_reopen_requested","project_reopen_approved","project_reopen_rejected"]}},{"name":"actorMembershipId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"dateFrom","required":false,"in":"query","description":"Inclusive lower bound on `occurredAt`, e.g. `\"2026-09-01\"`.","schema":{"format":"date","type":"string"}},{"name":"dateTo","required":false,"in":"query","description":"Inclusive upper bound on `occurredAt`.","schema":{"format":"date","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the project's audit trail.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AuditEventDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project's audit trail","tags":["Audit"]}},"/api/suppliers":{"post":{"description":"Registers a party the organization may place purchase orders with.\n\n`supplierCode` is upper-cased on input and unique within the organization, so `acme` and `ACME` cannot become two payees — a duplicate returns 409. So is `taxRegistrationNumber` (spaces removed), since two suppliers sharing one are the same supplier entered twice. The supplier is always created ACTIVE; creating one pre-retired is not permitted, since it would be a way to smuggle an unusable payee past review.\n\nSeparate from `purchase_order.create` by design: a buyer who raises orders against the suppliers the firm already deals with is not therefore a person who may add new ones. That is the control that stops spend being routed to an unvetted payee.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSupplierDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A supplier with that code already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a supplier","tags":["Suppliers"]},"get":{"description":"The organization’s suppliers, ordered by name. `search` matches either the name or the code, case-insensitively.\n\nOrdering ends on the id so it is total: rows tied on name could otherwise swap between pages and be served twice or skipped.","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["ACTIVE","INACTIVE"]}},{"name":"supplierType","required":false,"in":"query","schema":{"type":"string","enum":["MATERIALS","SERVICES","SUBCONTRACTOR","PLANT_HIRE","CONSULTANT"]}},{"name":"search","required":false,"in":"query","description":"Case-insensitive partial match on the name, the code or the tax\nregistration number.","schema":{"maxLength":200,"type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of suppliers.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SupplierDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List suppliers","tags":["Suppliers"]}},"/api/suppliers/{supplierId}":{"get":{"description":"A supplier belonging to another organization returns 404, identically to one that does not exist — a 403 would confirm it exists and disclose the platform’s client list.","operationId":"findOne","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a supplier","tags":["Suppliers"]},"patch":{"description":"Updates contact details, or sets `status` to INACTIVE to retire the supplier.\n\n`supplierCode` cannot be changed: it is how this supplier appears on every order already placed, so re-coding it would silently rewrite that paperwork. A supplier coded wrongly is retired and replaced.\n\nRetiring bars **new** purchase orders — checked both when an order names the supplier and again when one is issued, since a supplier may be retired between drafting and issuing. Orders already issued are untouched: deactivation must not rewrite history.\n\nThere is no delete. A supplier named on an order must stay readable for that order to make sense, and the composite foreign key from `purchase_order` would refuse the delete regardless.","operationId":"update","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSupplierDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a supplier, or retire it","tags":["Suppliers"]}},"/api/suppliers/{supplierId}/contacts":{"get":{"description":"Everyone worth reaching beyond the primary contact on the supplier itself, ordered by name.","operationId":"list","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SupplierContactDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a supplier’s contacts","tags":["Suppliers"]},"post":{"operationId":"create","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSupplierContactDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierContactDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a contact to a supplier","tags":["Suppliers"]}},"/api/suppliers/{supplierId}/contacts/{contactId}":{"patch":{"operationId":"update","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"contactId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSupplierContactDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierContactDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier or contact in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a supplier contact","tags":["Suppliers"]},"delete":{"description":"Deleted outright: nothing references a contact, so removing one rewrites no history.","operationId":"remove","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"contactId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The contact was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier or contact in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a supplier contact","tags":["Suppliers"]}},"/api/suppliers/{supplierId}/bank-accounts":{"get":{"description":"Default first, then verified, then pending verification, then retired — newest first within each. Retired accounts are kept: they are the record of where this supplier has been paid.","operationId":"list","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SupplierBankAccountDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a supplier’s bank accounts","tags":["Suppliers"]},"post":{"description":"The account starts PENDING_VERIFICATION and cannot be paid into until another member verifies it.\n\nAccounts are never edited. If a supplier says their account has changed, record the new one, have it verified independently — by phoning a contact you already hold, not one given in the request — and retire the old one.","operationId":"record","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSupplierBankAccountDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierBankAccountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The same bank and account number is already recorded and not retired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Record a bank account for a supplier","tags":["Suppliers"]}},"/api/suppliers/{supplierId}/bank-accounts/{accountId}/verify":{"post":{"description":"Confirms an account another member recorded. The recorder can never verify their own entry — the database refuses it as well.\n\nThe supplier’s first verified account becomes its default; pass `makeDefault: true` to move the default to this one. Idempotent: verifying a verified account returns it unchanged.","operationId":"verify","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"accountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifySupplierBankAccountDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierBankAccountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\nYou recorded this account, so you cannot verify it."},"404":{"description":"No such supplier or account in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The account is retired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Verify a supplier bank account","tags":["Suppliers"]}},"/api/suppliers/{supplierId}/bank-accounts/{accountId}/default":{"post":{"operationId":"makeDefault","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"accountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierBankAccountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier or account in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The account is not verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Make a verified account the supplier’s default","tags":["Suppliers"]}},"/api/suppliers/{supplierId}/bank-accounts/{accountId}/retire":{"post":{"description":"Terminal, and needs a reason. Retiring the default leaves the supplier with no default on purpose — choosing where money goes next is a decision, not a side effect. Idempotent.","operationId":"retire","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"accountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetireSupplierBankAccountDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierBankAccountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier or account in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Retire a supplier bank account","tags":["Suppliers"]}},"/api/purchase-orders":{"post":{"description":"Creates a DRAFT order against an **approved** requisition, optionally with its lines, in one transaction — so an order never lands half-built.\n\nThe requisition must be APPROVED: an order against an unapproved request would be a commitment nobody authorized. Note that an organization with no active approval policy leaves requisitions SUBMITTED forever rather than auto-approving, and such a requisition is correctly refused here.\n\nThe project is taken from the requisition, never supplied separately. The supplier must be ACTIVE. Both are re-checked at issue rather than trusted from here.\n\n`purchaseOrderNumber` is generated server-side as `PO-0001`, sequential within the project under an advisory lock, with a unique constraint as the actual guarantee.\n\nA draft commits nothing: it consumes no requisition quantity and adds nothing to a budget line’s committed figure. Issuing does both.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchaseOrderDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe requisition is not approved, not in your organization, or the supplier is inactive or unknown."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A platform administrator with no membership here cannot be recorded as the buyer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Raise a draft purchase order","tags":["Procurement"]},"get":{"description":"Every order in the organization, newest first. Filterable by `status`, `supplierId` and `requisitionId`. Use `GET /projects/{projectId}/purchase-orders` to scope to one project.","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","ISSUED","CANCELLED","CLOSED"]}},{"name":"supplierId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"requisitionId","required":false,"in":"query","description":"Restrict to orders procuring one requisition.","schema":{"format":"uuid","type":"string"}},{"name":"projectId","required":false,"in":"query","description":"Restrict the organization-wide register to one project. Ignored on\n`/projects/:projectId/purchase-orders`, where the path already scopes it.","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Case-insensitive match on the order number, supplier name or code, or the\nrequisition number. Wildcards are literal.","schema":{"maxLength":200,"example":"PO-0012","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of purchase orders.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List purchase orders","tags":["Procurement"]}},"/api/purchase-orders/{purchaseOrderId}":{"get":{"description":"An order belonging to another organization returns 404, identically to one that does not exist — a 403 would confirm it exists and disclose the platform’s client list.","operationId":"findOne","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a purchase order","tags":["Procurement"]},"patch":{"description":"**DRAFT only.** An ISSUED, CANCELLED or CLOSED order returns 409: an issued order is what the supplier was told to deliver and what the organization committed to pay, so if it could still be edited the commitment recorded against a budget and the commitment the supplier holds could differ with nothing recording the change.\n\nThere is no amend-an-issued-order path in D.8. A price renegotiated after issue, or a quantity the supplier cannot meet, is handled by cancelling and re-raising — which is honest about there having been two commitments. Amendment with revisions is a genuinely larger feature (revision numbers, a supersession chain, a rule for which revision a receipt matches) and is deferred rather than half-built.\n\n`requisitionId` and `purchaseOrderNumber` are not accepted: the first would make every line’s provenance wrong at once, and the second is quoted to a supplier the moment it exists. Status moves only through the explicit action routes.","operationId":"update","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePurchaseOrderDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe named supplier is inactive or unknown."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The order is not a draft and cannot be changed; or `STALE_WRITE`: `expectedUpdatedAt` was sent and the order has been saved since.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft purchase order","tags":["Procurement"]}},"/api/purchase-orders/{purchaseOrderId}/issue":{"post":{"description":"**The act that commits the organization.** Everything below happens in one transaction.\n\nThe requisition is re-read and must still be APPROVED; the supplier re-read and must still be ACTIVE. Both were checked when the draft was raised and neither is trusted from then — a supplier retired in between must not be bound at the moment the firm commits.\n\nEvery requisition line the order draws on is locked FOR UPDATE, and cumulative **issued** quantity is summed under that lock and compared with what the requisition requested. Over-ordering is refused with 409. This is the one place D.8 blocks rather than reports, because the authorization is a fixed quantity rather than a budget figure the firm may knowingly exceed. Approval is all-or-nothing in this system, so the requested quantity *is* the approved quantity.\n\nBudget remaining across the order’s lines is read live — never from cache — and snapshotted to `budgetRemainingAtIssue`. **An over-budget order still issues**, and a negative snapshot is exactly the case worth recording: every layer of this system reports the overrun and makes it provably deliberate rather than blocking it.\n\nOf two concurrent issue requests exactly one wins, guarded by a conditional UPDATE. Re-issuing an already-issued order succeeds unchanged, so a client that lost the response need not reason about whether it committed.\n\nAn order with no lines is refused: there is nothing to commit to.","operationId":"issue","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe requisition is no longer approved, or the supplier is now inactive."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The order is not a draft, has no lines, would order more than the requisition authorized, or the caller has no membership here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Issue the purchase order","tags":["Procurement"]}},"/api/purchase-orders/{purchaseOrderId}/cancel":{"post":{"description":"Legal from DRAFT and from ISSUED, and the two are different acts sharing a name: discarding a document nobody was shown, versus retracting a commitment a supplier already holds.\n\nA reason is required for both — enforced here and again by a database CHECK — because a blank one is impossible to reconstruct later.\n\nCancelling **releases** the order’s quantity and its committed value immediately, and needs no release mechanism to do so: both figures are derived from the set of issued and closed orders, so a cancelled order simply stops counting. That is the whole benefit of never having reserved anything.\n\nTerminal. Re-cancelling succeeds unchanged.","operationId":"cancel","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelPurchaseOrderDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The order is already closed, and cannot be cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Cancel the purchase order","tags":["Procurement"]}},"/api/purchase-orders/{purchaseOrderId}/close":{"post":{"description":"Retires an order that is finished with — completed, abandoned by the supplier, or superseded.\n\nA closed order **still counts** toward ordered quantity and committed value: it was genuinely placed, so excluding it would free quantity that really was ordered and make a budget’s committed figure drop the moment a buyer tidied up. That is the difference between closing and cancelling.\n\nReachable only from ISSUED. Closing a draft is cancelling it, and two names for one act would let the same situation be recorded two ways.\n\nShares the `purchase_order.cancel` permission: both are the authority to retire an order, and splitting them would grant a power nobody asks for separately. Terminal; re-closing succeeds unchanged.","operationId":"close","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Only an issued order can be closed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Close an issued purchase order","tags":["Procurement"]}},"/api/purchase-orders/{purchaseOrderId}/lines":{"get":{"description":"Ordered by `sortOrder` then id, so the ordering is total and pagination is stable.\n\nEach line carries its provenance joined in rather than duplicated — `budgetLineId`, `boqItemCode` and `costCentreCode` come from the requisition line’s own budget line, so they cannot disagree with it. There is deliberately no `budgetLineId` column on a purchase order line.\n\n`requestedQuantity` and `orderedQuantity` sit beside each line’s own `quantity` so an over-order is visible here rather than only at the moment issue refuses it. `orderedQuantity` counts issued and closed orders other than this one.","operationId":"listLines","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the order’s lines.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderLineDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List an order’s lines","tags":["Procurement"]},"post":{"description":"**DRAFT only.** The requisition line must belong to this order’s own requisition — proved by composite foreign key, not by service code a bulk import could bypass.\n\nOne order bills a need once: a second line against the same requisition line returns 409. Two lines against one need would make the ordered-quantity ledger ambiguous and let a buyer split a quantity past its limit inside a single document, where the cross-document check would not look.\n\n`description`, `unit` and `unitPrice` default from the requisition line when omitted. The price defaults from the requester’s *estimate* — a starting point a buyer is expected to overwrite with what the supplier actually quoted. A buyer who leaves it has accepted the estimate as the agreed price, which is recorded as such.\n\n`lineAmount` is computed by PostgreSQL as `quantity × unitPrice`; sending it returns 400.\n\nA draft line may exceed the requested quantity freely — the refusal happens at issue, under a row lock, which is the only place it can be correct when two buyers are drafting at once.","operationId":"createLine","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchaseOrderLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe requisition line is not on this order’s requisition."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The order is not a draft, or already has a line for that requisition line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a line to a draft order","tags":["Procurement"]}},"/api/purchase-orders/{purchaseOrderId}/lines/{lineId}":{"patch":{"description":"**DRAFT only.** `requisitionLineId` is not accepted: which need a line procures is its identity, not an editable attribute, and re-pointing it would silently move a commitment between authorizations. Correcting a mis-pointed line means removing it and adding the right one.","operationId":"updateLine","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePurchaseOrderLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such order or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The order is not a draft and cannot be changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a line on a draft order","tags":["Procurement"]},"delete":{"description":"**DRAFT only.** Removing a line from an issued order is not possible — the order is what the supplier was told to deliver.","operationId":"removeLine","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The line was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such order or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The order is not a draft and cannot be changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from a draft order","tags":["Procurement"]}},"/api/projects/{projectId}/purchase-orders":{"get":{"description":"Newest first. Filterable by `status`, `supplierId` and `requisitionId`.\n\n`totalAmount` on each order is the sum of its lines, computed by the database on every read and never stored — a persisted total is a second source of truth that disagrees with its own lines the first time one is written outside the service.\n\nOrdering ends on the id so it is total: orders created in the same instant could otherwise swap between pages and be served twice or skipped.","operationId":"list","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","ISSUED","CANCELLED","CLOSED"]}},{"name":"supplierId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"requisitionId","required":false,"in":"query","description":"Restrict to orders procuring one requisition.","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Case-insensitive match on the order number, supplier name or code, or the\nrequisition number. Wildcards are literal.","schema":{"maxLength":200,"example":"PO-0012","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the project’s purchase orders.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s purchase orders","tags":["Procurement"]}},"/api/requisitions/{requisitionId}/procurement":{"get":{"description":"Per requisition line: what was requested, how much has been ordered on ISSUED or CLOSED purchase orders, and what remains. This is the read that makes partial procurement workable — a buyer splitting an order across suppliers or over time needs to know what is still outstanding.\n\n`requestedQuantity` **is** the approved quantity: approval in this system is all-or-nothing on the whole requisition, and a requisition locks the moment it is submitted, so what was requested is exactly what the approver saw and authorized.\n\nDrafts are excluded, so the figure can be optimistic while several buyers are drafting at once. That is deliberate and matches how the rule is enforced: only issuing consumes quantity, and issuing re-checks under a row lock. A draft that looks affordable here may still be refused at issue if somebody else issued first.\n\nNot a reporting engine: it answers one question about one requisition.","operationId":"remainingQuantities","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RequisitionProcurementDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"What remains to be ordered against a requisition","tags":["Procurement"]}},"/api/procurement/summary":{"get":{"description":"Order counts by status and by receipt status, and committed, open and draft order value, for every order matching `projectId` and `supplierId` — not one page.\n\nMoney is a decimal string **per currency** and is never converted. `receipts` is `null` unless you hold `goods_receipt.view`, and `requisitions` is `null` unless you hold `requisition.view`: the summary never shows figures its source registers would not. `supplierId` does not narrow requisitions, which name no supplier.\n\n`budget` compares the project’s ACTIVE budget with what orders commit and requisitions still claim. It is `null` unless `projectId` is given and you hold `budget.view`, and is never narrowed by `supplierId`.","operationId":"summary","parameters":[{"name":"projectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"supplierId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementSummaryDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Procurement summary","tags":["Procurement"]}},"/api/goods-receipts":{"post":{"description":"Opens a **draft** receipt against an issued purchase order, optionally with its lines.\n\nThe order is the only thing you name: the project, the organization and the supplier all follow from it, so a receipt cannot be filed against one order but recorded under another project.\n\nGoods may arrive against an `ISSUED` or `CLOSED` order. A `DRAFT` order has been given to no supplier, and a `CANCELLED` one is a retracted commitment that cannot yield goods.\n\nSome orders are never received against at all — a requisition type marked as not receivable records something settled rather than delivered, such as a cash advance.\n\nA draft attests nothing and counts toward nothing. Posting it is the act that matters.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGoodsReceiptDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoodsReceiptDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe order is not in a receivable state, or its requisition type is not received against."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"You have no membership in this organization to record as the receiver.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Record a goods receipt","tags":["Goods Receipts"]},"get":{"description":"Every receipt in the organization, newest first. Filterable by `status` and `purchaseOrderId`. Use `GET /projects/{projectId}/goods-receipts` to scope to one project.","operationId":"list","parameters":[{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","POSTED","CANCELLED"]}},{"name":"purchaseOrderId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"projectId","required":false,"in":"query","description":"Restrict the organization-wide register to one project. Ignored on\n`/projects/:projectId/goods-receipts`, where the path already scopes it.","schema":{"format":"uuid","type":"string"}},{"name":"supplierId","required":false,"in":"query","description":"Restrict to receipts against one supplier's orders.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"A page of goods receipts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/GoodsReceiptDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List goods receipts","tags":["Goods Receipts"]}},"/api/goods-receipts/{goodsReceiptId}":{"get":{"description":"A receipt belonging to another organization returns 404, identically to one that does not exist — a 403 would confirm it exists and disclose the platform’s client list.","operationId":"findOne","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoodsReceiptDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a goods receipt","tags":["Goods Receipts"]},"patch":{"description":"Only the delivery note reference, unloading location, received date and notes. Which order a receipt records is its identity and cannot be changed; the status moves only through the post and cancel actions.\n\nA **posted receipt is immutable**. Correcting one means cancelling it and recording another, which is honest about there having been two attestations.","operationId":"update","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGoodsReceiptDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoodsReceiptDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"This receipt is posted or cancelled and cannot be changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft goods receipt","tags":["Goods Receipts"]}},"/api/goods-receipts/{goodsReceiptId}/post":{"post":{"description":"The act that attests the goods arrived and counts them against the order. Its own permission: keying in a delivery note is not the same authority as signing that the goods came.\n\n**Over-receiving is refused.** Cumulative posted quantity across every receipt against one order line may not exceed what was ordered. Drafts may exceed it freely and report how much room is left; only posting refuses, because two storekeepers may both draft against the same line and only one of them can post past the limit.\n\nThe check runs in PostgreSQL under a row lock on the order lines, and the arithmetic is exact decimal. An order for `0.3000` m³ delivered as `0.1000` then `0.2000` posts successfully — in floating point that sum exceeds `0.3` and would be wrongly refused.\n\nPosting an already-posted receipt returns it unchanged rather than failing, so a retried request is safe.","operationId":"post","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoodsReceiptDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe order is no longer in a receivable state."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The receipt has no lines, is cancelled, or posting would receive more than was ordered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Post a goods receipt","tags":["Goods Receipts"]}},"/api/goods-receipts/{goodsReceiptId}/cancel":{"post":{"description":"Two acts sharing one name. Cancelling a **draft** discards a document that attested nothing. Cancelling a **posted** receipt reverses an attestation that has already counted against an order, which is why the reason is required and the person recorded.\n\nNothing is unwound mechanically, because nothing was ever reserved: a cancelled receipt simply stops counting, and the ordered quantity is available again immediately.","operationId":"cancel","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelGoodsReceiptDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoodsReceiptDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"This receipt is already cancelled, its stock has since been issued (`GOODS_RECEIPT_REVERSAL_INSUFFICIENT_STOCK`), or goods have been returned to the supplier against it (`GOODS_RECEIPT_HAS_SUPPLIER_RETURNS`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Cancel or reverse a goods receipt","tags":["Goods Receipts"]}},"/api/goods-receipts/{goodsReceiptId}/lines":{"get":{"description":"Each line carries what was ordered beside what arrived, and how much of the order line other posted receipts already account for — so an over-receipt is visible on the draft rather than only when posting refuses it.","operationId":"listLines","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the receipt’s lines.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/GoodsReceiptLineDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a receipt’s lines","tags":["Goods Receipts"]},"post":{"description":"The ordered item must belong to this receipt’s own purchase order, and a receipt may record each ordered item only once — two lines against one order line would make the received quantity ambiguous.\n\nThe unit is copied from the order line and cannot be set: receiving in a different unit from the one ordered would compare incommensurable quantities, and this system has no conversion authority.","operationId":"createLine","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGoodsReceiptLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoodsReceiptLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThat order line is not on this receipt’s purchase order."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The receipt is posted or cancelled, or already records that ordered item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a line to a draft receipt","tags":["Goods Receipts"]}},"/api/goods-receipts/{goodsReceiptId}/lines/{lineId}":{"patch":{"description":"The ordered item a line receives against cannot be changed — re-pointing it would silently move an attestation from one commitment to another.","operationId":"updateLine","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGoodsReceiptLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoodsReceiptLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The receipt is posted or cancelled and cannot be changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft receipt’s line","tags":["Goods Receipts"]},"delete":{"description":"Only while the receipt is a draft. A posted receipt’s lines are what someone attested arrived.","operationId":"removeLine","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The receipt is posted or cancelled and cannot be changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from a draft receipt","tags":["Goods Receipts"]}},"/api/goods-receipts/{goodsReceiptId}/attachments":{"post":{"description":"The supplier’s delivery note, a signed waybill, photographs of what arrived. JPEG, PNG, WebP or PDF, checked by content. Allowed on DRAFT and POSTED receipts — the signed waybill often follows the goods — but not on a CANCELLED one (`409 GOODS_RECEIPT_ATTACHMENT_LOCKED`).","operationId":"attach","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"caption":{"type":"string"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The goods receipt is cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Attach a supporting document to a goods receipt","tags":["Goods Receipts"]},"get":{"operationId":"listAttachments","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a goods receipt’s supporting documents","tags":["Goods Receipts"]}},"/api/goods-receipts/{goodsReceiptId}/attachments/{attachmentId}":{"delete":{"description":"**DRAFT only.** Once posted, a receipt’s documents are the evidence it was attested against and are kept (`409 GOODS_RECEIPT_ATTACHMENT_LOCKED`).","operationId":"removeAttachment","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"attachmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The document was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt or document in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The goods receipt is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a supporting document from a draft goods receipt","tags":["Goods Receipts"]}},"/api/projects/{projectId}/goods-receipts":{"get":{"description":"Every delivery recorded on one project, newest first. The project is resolved first, so an id from another organization returns 404 rather than an empty page — an empty page would confirm the project does not exist here.","operationId":"listForProject","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","POSTED","CANCELLED"]}},{"name":"purchaseOrderId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"supplierId","required":false,"in":"query","description":"Restrict to receipts against one supplier's orders.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"A page of goods receipts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/GoodsReceiptDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s goods receipts","tags":["Goods Receipts"]}},"/api/purchase-orders/{purchaseOrderId}/goods-receipts":{"get":{"description":"Every delivery recorded against one purchase order — the receiving history a buyer chasing a supplier reads. One order may have many receipts; that is what makes partial delivery work.","operationId":"listForOrder","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","POSTED","CANCELLED"]}},{"name":"projectId","required":false,"in":"query","description":"Restrict the organization-wide register to one project. Ignored on\n`/projects/:projectId/goods-receipts`, where the path already scopes it.","schema":{"format":"uuid","type":"string"}},{"name":"supplierId","required":false,"in":"query","description":"Restrict to receipts against one supplier's orders.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"A page of goods receipts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/GoodsReceiptDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List an order’s goods receipts","tags":["Goods Receipts"]}},"/api/purchase-orders/{purchaseOrderId}/receiving":{"get":{"description":"Ordered, received and remaining for each line of one order, with the received value at the agreed prices.\n\nReceived quantity sums **posted** receipts only — a draft attests nothing and a cancelled receipt counts for nothing. Every figure is computed in PostgreSQL as exact decimal and served as a string.\n\nNothing here is stored: a purchase order has no receiving status column, because a stored one would be a second source of truth that disagrees with its own receipts the first time one is posted or reversed.","operationId":"receivingSummary","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderReceivingDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"An order’s receiving position","tags":["Goods Receipts"]}},"/api/stock-items":{"post":{"description":"Creates the identity the stock ledger keys on. `code` is upper-cased, so `cem-42.5n` and `CEM-42.5N` cannot become two items holding two halves of one balance; omit it and one is generated from the category and name.\n\nFiled under `categoryId` (and optionally a `subcategoryId` of it), or under \"Uncategorised\" when omitted. The item starts with **no stock**: quantities arrive only through a receipt or an approved stock count. `unitCost` is its average cost until the first priced receipt replaces it.\n\n`isStockControlled` defaults to `true`. Set it `false` for something received but never held — consultancy, subcontract work, plant hire — which then posts through goods receiving without producing any stock movement.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStockItemDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItemDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such category, subcategory or supplier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The code is taken, or the subcategory is not under the category.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a stock item","tags":["Inventory"]},"get":{"description":"A page of the catalogue — for pickers, searched as people type. `q` matches code or name; `categoryId` takes a category with its subcategories, or one subcategory. By code unless sorted otherwise.","operationId":"list","parameters":[{"name":"q","required":false,"in":"query","description":"Code or name contains this, ignoring case.","schema":{"maxLength":100,"type":"string"}},{"name":"categoryId","required":false,"in":"query","description":"A category — its subcategories included — or one subcategory.","schema":{"format":"uuid","type":"string"}},{"name":"itemType","required":false,"in":"query","schema":{"type":"string","enum":["MATERIAL","EQUIPMENT"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["ACTIVE","INACTIVE"]}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"default":"code","example":"createdAt","type":"string","enum":["code","name","createdAt"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of stock items.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockItemDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List stock items","tags":["Inventory"]}},"/api/stock-items/similar":{"get":{"description":"Up to five items whose names look like `name` once case, spacing and punctuation are set aside — for warning about a duplicate before one is added. Inactive items are included; items merged away are not. A warning, never a block.","operationId":"similar","parameters":[{"name":"name","required":true,"in":"query","schema":{"minLength":3,"maxLength":200,"type":"string"}},{"name":"excludeId","required":false,"in":"query","description":"Leave this item out — the one being edited.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SimilarStockItemDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Items with a similar name","tags":["Inventory"]}},"/api/stock-items/code-available":{"get":{"description":"For checking a code as it is typed. Codes are compared upper-cased, as they are stored.","operationId":"codeAvailable","parameters":[{"name":"code","required":true,"in":"query","schema":{"maxLength":32,"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItemCodeAvailabilityDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Is this code free?","tags":["Inventory"]}},"/api/stock-items/{stockItemId}":{"get":{"description":"An item belonging to another organization returns `404`, identically to one that does not exist — a `403` would confirm it exists.","operationId":"findOne","parameters":[{"name":"stockItemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItemDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock item in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a stock item","tags":["Inventory"]},"patch":{"description":"`code` cannot be changed: it is the identity the ledger keys on, and re-coding an item that already has movements would re-file its history under another name. Mis-coded items are deactivated and replaced, or merged.\n\nChanging `categoryId` without `subcategoryId` clears the subcategory. Deactivating is refused while any store holds the item (`409 STOCK_ITEM_HAS_STOCK`). Re-filing, edits and status changes are written to the item’s history.\n\nChanging `isStockControlled` affects only FUTURE receipts. Movements already in the ledger are never rewritten — a balance that changed because somebody edited a catalogue flag would be unexplainable.","operationId":"update","parameters":[{"name":"stockItemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStockItemDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItemDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock item in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The subcategory is not under the category, or the item is still held.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a stock item","tags":["Inventory"]}},"/api/stock-items/{stockItemId}/history":{"get":{"description":"What happened to the catalogue entry — added, re-filed, edited, deactivated, merged — newest first. Stock movements are the ledger’s, not here.","operationId":"history","parameters":[{"name":"stockItemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of history.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockItemEventDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock item in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"An item’s history","tags":["Inventory"]}},"/api/stock-items/{stockItemId}/merge-preview":{"get":{"description":"What would move to `targetStockItemId` — stock on hand, ledger movements, document lines — and, in `blockers`, anything that stops the merge now.","operationId":"mergePreview","parameters":[{"name":"stockItemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"targetStockItemId","required":true,"in":"query","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItemMergePreviewDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock item in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Preview merging this item into another","tags":["Inventory"]}},"/api/stock-items/{stockItemId}/merge":{"post":{"description":"Folds a duplicate into `targetStockItemId`: its stock, ledger movements and document lines move across, the target’s average cost is re-weighted over both holdings, and this item is deactivated and marked as merged. Recorded in both items’ history. **Cannot be undone.**\n\nRefused with `409 STOCK_ITEM_MERGE_BLOCKED` when the units differ, either item is on an open stock count, or the two were counted at the same place — anything that would leave the ledger wrong.","operationId":"merge","parameters":[{"name":"stockItemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeStockItemDto"}}}},"responses":{"201":{"description":"The item that stays.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItemDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock item in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The merge is blocked; the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Merge this item into another","tags":["Inventory"]}},"/api/stock-items/{stockItemId}/photo":{"post":{"description":"One image in the `file` part: JPEG, PNG, WebP or HEIC/HEIF, checked by its content rather than its name, up to 5 MB (`413 IMAGE_TOO_LARGE`). Anything else is `400 UNSUPPORTED_IMAGE_TYPE`.\n\nThe image is re-encoded as WebP: a main image within 1600 px and a 160 px square thumbnail. HEIC is converted, the EXIF orientation is applied, and all metadata, GPS included, is removed. A photo already on the item is replaced, and its files are deleted once the new one is saved. Recorded in the item’s history as added or replaced.","operationId":"setPhoto","parameters":[{"name":"stockItemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItemDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock item in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"413":{"description":"Image is larger than 5 MB."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Set the item’s photo","tags":["Inventory"]},"delete":{"description":"Deletes the photo and its thumbnail. Recorded in the item’s history.","operationId":"removePhoto","parameters":[{"name":"stockItemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The photo was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock item, or it has no photo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove the item’s photo","tags":["Inventory"]}},"/api/stock-items/{stockItemId}/cost-changes":{"post":{"description":"Nothing changes until someone else approves it. One change per item may wait at a time.","operationId":"propose","parameters":[{"name":"stockItemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposeStockItemCostDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItemCostChangeDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock item in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The item already has a cost change waiting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"422":{"description":"The proposed cost is already the item’s cost."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Propose a new unit cost for a stock item","tags":["Inventory"]},"get":{"description":"Lets the proposer see whether a change is still waiting.","operationId":"listForItem","parameters":[{"name":"stockItemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of cost changes.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockItemCostChangeDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List one item’s cost changes","tags":["Inventory"]}},"/api/stock-item-cost-changes":{"get":{"description":"Newest first. Filter by `status` — `PENDING` is the approver’s queue.","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of cost changes.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockItemCostChangeDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List cost changes","tags":["Inventory"]}},"/api/stock-item-cost-changes/{changeId}/approve":{"post":{"description":"By someone other than its proposer. Revalues the stock on hand and writes `COST_CHANGED` to the item’s history.","operationId":"approve","parameters":[{"name":"changeId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItemCostChangeDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such cost change in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The change has already been decided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Approve a cost change, resetting the item’s average cost","tags":["Inventory"]}},"/api/stock-item-cost-changes/{changeId}/reject":{"post":{"description":"A reason is required. The item’s cost is untouched.","operationId":"reject","parameters":[{"name":"changeId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItemCostDecisionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItemCostChangeDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such cost change in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The change has already been decided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Reject a cost change","tags":["Inventory"]}},"/api/stock-categories/tree":{"get":{"description":"Every active category with its subcategories, in the order the stores team set, each with how many active items it holds. `itemType` counts only materials or only equipment.","operationId":"tree","parameters":[{"name":"itemType","required":false,"in":"query","description":"Count only items of this type. Omit to count every item.","schema":{"type":"string","enum":["MATERIAL","EQUIPMENT"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCategoryTreeDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"The category tree","tags":["Inventory"]}},"/api/stock-categories":{"post":{"description":"With `parentId`, a subcategory of that category. Two levels only: a subcategory cannot have subcategories (`409 STOCK_CATEGORY_TOO_DEEP`). Names are unique per parent, ignoring case (`409 DUPLICATE_STOCK_CATEGORY_NAME`).","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStockCategoryDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCategoryDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such parent category in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Duplicate name, or the parent is itself a subcategory.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a category or subcategory","tags":["Inventory"]}},"/api/stock-categories/reorder":{"post":{"description":"Every active category under `parentId` (null for the top level), first to last. A list that no longer matches — someone added or removed one meanwhile — is refused with `409 STOCK_CATEGORY_ORDER_STALE`.","operationId":"reorder","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderStockCategoriesDto"}}}},"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The list is out of date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Reorder one level of the tree","tags":["Inventory"]}},"/api/stock-categories/{categoryId}":{"patch":{"operationId":"rename","parameters":[{"name":"categoryId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStockCategoryDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCategoryDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such category in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Another category here already has that name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Rename a category or subcategory","tags":["Inventory"]},"delete":{"description":"Refused with `409 STOCK_CATEGORY_IN_USE` while any active item is filed under it or it has active subcategories. Removal keeps the row — items deactivated earlier still name it.","operationId":"remove","parameters":[{"name":"categoryId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such category in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Items or subcategories still use it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a category or subcategory","tags":["Inventory"]}},"/api/stores":{"post":{"description":"Omit `projectId` for a central store serving the whole firm; set it for a store belonging to one site. The distinction is descriptive — stock is owned by the store either way, and nothing scopes a balance or a permission by project.\n\nA store is not a branch: a branch is where the firm operates, a store is where the cement is, and one branch may hold several stores.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStoreDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A store with this code already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create a store","tags":["Inventory"]},"get":{"description":"Every store in the organization, by code.","operationId":"list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StoreDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List stores","tags":["Inventory"]}},"/api/stores/{storeId}":{"get":{"description":"A store belonging to another organization returns `404`, identically to one that does not exist.","operationId":"findOne","parameters":[{"name":"storeId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such store in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a store","tags":["Inventory"]},"patch":{"description":"Neither `code` nor `projectId` can be changed: moving a store between projects after it holds stock would re-file the provenance of every movement in it. A store set up wrongly is deactivated and replaced.","operationId":"update","parameters":[{"name":"storeId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStoreDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such store in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a store","tags":["Inventory"]}},"/api/stores/{storeId}/locations":{"post":{"description":"A location narrows a store; it does not own stock. Balances remain the store’s, and a movement with no location is simply \"in the store, no bin recorded\".\n\nOnly `BIN` can be created. Every store already has exactly one `TRANSIT` location, provisioned with the store and used only by stock transfers; requesting another is refused with `409`, as is the reserved code `TRANSIT`.","operationId":"create","parameters":[{"name":"storeId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStoreLocationDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreLocationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such store in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A location with this code already exists in this store (`DUPLICATE_STORE_LOCATION_CODE`), the code is reserved (`STORE_LOCATION_CODE_RESERVED`), or the type is not creatable (`STORE_LOCATION_TYPE_NOT_AVAILABLE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Create a location in a store","tags":["Inventory"]},"get":{"description":"Every location in the store, by code — including its system-managed `TRANSIT` location, where stock dispatched from this store waits to be received.","operationId":"list","parameters":[{"name":"storeId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StoreLocationDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such store in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a store’s locations","tags":["Inventory"]}},"/api/stores/{storeId}/locations/{locationId}":{"get":{"description":"A location addressed through a store it is not in, or belonging to another organization, returns `404`.","operationId":"findOne","parameters":[{"name":"storeId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"locationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreLocationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such location in this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a location","tags":["Inventory"]},"patch":{"description":"Neither `code` nor `locationType` can be changed once created. An inactive location cannot receive goods; stock already in it stays in it until moved by a stock transfer. The `TRANSIT` location cannot be changed at all (`TRANSIT_LOCATION_MANAGED`): deactivating it would strand goods on the road.","operationId":"update","parameters":[{"name":"storeId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"locationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStoreLocationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreLocationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such location in this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The location is the store’s transit location.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a location","tags":["Inventory"]}},"/api/stock-balances":{"get":{"description":"On-hand quantity summed from the ledger on every read — there is no stored balance anywhere in this system, so each figure here is explainable by the movements behind it. `groupBy` selects the grain: per store and item (default), per store, bin and item, or per item across stores.\n\nStock in transit is stock: a dispatched transfer’s goods sit in the source store’s `TRANSIT` location until received, so they count in the `store` and `item` totals and appear as their own row (`storeLocationType: TRANSIT`) under `groupBy=location`.\n\nFilterable by `storeId`, `storeLocationId`, `stockItemId` and `projectId` (the project’s own site stores). An item whose movements net to zero is omitted: a receipt that was posted and then reversed leaves history but no stock, and listing it as `0` would put noise where a reader expects holdings. Its movements remain visible through `GET /stock-movements`.","operationId":"balances","parameters":[{"name":"groupBy","required":false,"in":"query","description":"`store` (default): per store and item. `location`: per store, bin and item — a null location is stock in the store with no bin recorded. `item`: per item across stores; the store and location fields are then null.","schema":{"default":"store","type":"string","enum":["store","location","item"]}},{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"storeLocationId","required":false,"in":"query","description":"Only stock recorded in this location (bin).","schema":{"format":"uuid","type":"string"}},{"name":"projectId","required":false,"in":"query","description":"**Ownership**: stock held in this project’s own site stores. Stock is owned by the store, so central-store stock bought against the project is not included — its movements carry the project as provenance, filterable on `GET /stock-movements`.","schema":{"format":"uuid","type":"string"}},{"name":"stockItemId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of stock balances.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockBalanceDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Current stock","tags":["Inventory"]}},"/api/stock-movements":{"get":{"description":"The ledger itself, newest first. Every row names its store, item, signed quantity, the document that caused it, the person who caused it and when — which is how \"why does this balance read what it reads?\" is answered.\n\nFilterable by `storeId`, `storeLocationId`, `stockItemId`, `goodsReceiptId`, `materialIssueId`, `stockTransferId`, `projectId` (the project whose document caused the movement), `movementType`, and a half-open `movedFrom`/`movedTo` window. Quantities are signed: a `RECEIPT` is positive, a `REVERSAL` negative, and a reversal names the movement it undoes in `reversesMovementId`. Reversals never delete or edit the row they undo.\n\nA `TRANSFER` is always one of a pair and names its `transferLeg`: dispatch writes `SOURCE_OUT` (negative, the source bin) and `TRANSIT_IN` (positive, the source store’s transit location); receipt writes `TRANSIT_OUT` and `DESTINATION_IN`.","operationId":"movements","parameters":[{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"storeLocationId","required":false,"in":"query","description":"Only movements into or out of this location (bin).","schema":{"format":"uuid","type":"string"}},{"name":"projectId","required":false,"in":"query","description":"**Provenance**: movements whose source document belongs to this project — e.g. receipts against its purchase orders. Distinct from the balance read’s `projectId`, which selects the project’s own stores.","schema":{"format":"uuid","type":"string"}},{"name":"movementType","required":false,"in":"query","schema":{"type":"string","enum":["RECEIPT","ISSUE","TRANSFER","ADJUSTMENT","RETURN","SUPPLIER_RETURN","REVERSAL","SALE"]}},{"name":"movedFrom","required":false,"in":"query","description":"Earliest `movedAt` to include, **inclusive**. An ISO 8601 instant with an explicit offset; a bare date is refused.","schema":{"example":"2026-09-01T00:00:00Z","type":"string"}},{"name":"movedTo","required":false,"in":"query","description":"End of the window, **exclusive**, so consecutive windows neither overlap nor leave a gap. Same format as `movedFrom`.","schema":{"example":"2026-10-01T00:00:00Z","type":"string"}},{"name":"stockItemId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"goodsReceiptId","required":false,"in":"query","description":"Every movement caused by one goods receipt.","schema":{"format":"uuid","type":"string"}},{"name":"materialIssueId","required":false,"in":"query","description":"Every movement caused by one material issue (D.11).","schema":{"format":"uuid","type":"string"}},{"name":"stockTransferId","required":false,"in":"query","description":"Every movement caused by one stock transfer (D.12): its dispatch legs and, once received, its receipt legs.","schema":{"format":"uuid","type":"string"}},{"name":"materialReturnId","required":false,"in":"query","description":"Every movement caused by one material return (D.13): its RETURN rows and, if reversed, their REVERSALs.","schema":{"format":"uuid","type":"string"}},{"name":"supplierReturnId","required":false,"in":"query","description":"Every movement caused by one supplier return (D.13).","schema":{"format":"uuid","type":"string"}},{"name":"inventoryAdjustmentId","required":false,"in":"query","description":"Every movement caused by one inventory adjustment (D.13).","schema":{"format":"uuid","type":"string"}},{"name":"stockCountId","required":false,"in":"query","description":"Every movement caused by one stock count (D.13): one ADJUSTMENT per position with a variance.","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of stock movements.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockMovementDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Stock movement history","tags":["Inventory"]}},"/api/inventory/settings":{"get":{"description":"Readable by anyone who can see stock or stock counts, since the overview’s alerts and the count approval chain are judged by these. The defaults until changed.","operationId":"get","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventorySettingsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get the inventory thresholds","tags":["Inventory"]},"patch":{"description":"Send only the thresholds that change. A new finance limit applies to counts approved from now on, not to one already awaiting finance.","operationId":"update","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventorySettingsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventorySettingsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Change the inventory thresholds","tags":["Inventory"]}},"/api/material-issues":{"get":{"description":"Every issue in the organization, newest first. Filterable by `status`, `projectId`, `requisitionId`, `storeId`, `receiverMembershipId`, `issuedByMembershipId` and a half-open `postedFrom`/`postedTo` window (instants with an offset).","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","POSTED","CANCELLED"]}},{"name":"projectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"requisitionId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"receiverMembershipId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"issuedByMembershipId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"postedFrom","required":false,"in":"query","description":"Earliest `postedAt`, **inclusive**. An ISO 8601 instant with an explicit offset.","schema":{"example":"2026-09-01T00:00:00Z","type":"string"}},{"name":"postedTo","required":false,"in":"query","description":"End of the `postedAt` window, **exclusive**.","schema":{"example":"2026-10-01T00:00:00Z","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of material issues.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MaterialIssueDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List material issues","tags":["Material Issues"]}},"/api/material-issues/{materialIssueId}":{"get":{"description":"Who released what, to whom, from which store, against which requisition, and when. An issue of another organization returns 404.","operationId":"findOne","parameters":[{"name":"materialIssueId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialIssueDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material issue in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a material issue","tags":["Material Issues"]},"patch":{"description":"The receiver, purpose, notes — and the store, while the issue has no lines. The requisition is the issue’s authority and cannot change. A **posted issue is immutable**; correct it by cancelling, which returns its stock.","operationId":"update","parameters":[{"name":"materialIssueId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMaterialIssueDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialIssueDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material issue, store or receiver.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The issue is posted or cancelled, the store has lines drawn on it, or the store or receiver is inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft material issue","tags":["Material Issues"]}},"/api/material-issues/{materialIssueId}/post":{"post":{"description":"Releases the stock: writes one negative `ISSUE` movement per line and records you as the issuer.\n\n**Negative stock is impossible.** Each (store, bin, item) must hold what the issue takes, checked in PostgreSQL under a lock on that stock position, so two issues racing for the last bag cannot both succeed. A line draws only on its own bin — never on another bin to make up a shortfall.\n\n**The requisition caps the quantity.** Posted issues against a requisition line may not exceed its approved quantity; drafts may, and show the room left.\n\nThe requisition must still be APPROVED, the receiver an active member, the store and bins active, and every item stock-controlled. Any refusal leaves the issue a draft with nothing written. Posting an already-posted issue returns it unchanged.","operationId":"post","parameters":[{"name":"materialIssueId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialIssueDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material issue in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`INSUFFICIENT_STOCK`, `ISSUED_QUANTITY_EXCEEDED`, `REQUISITION_NOT_APPROVED`, `MATERIAL_ISSUE_RECEIVER_REQUIRED`, `STOCK_SOURCE_INACTIVE`, `STOCK_ITEM_NOT_STOCK_CONTROLLED`, `EMPTY_MATERIAL_ISSUE`, or the issue is cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Post a material issue","tags":["Material Issues"]}},"/api/material-issues/{materialIssueId}/cancel":{"post":{"description":"Cancelling a **draft** discards it; nothing was released. Cancelling a **posted** issue states it was **recorded in error — the goods never left the store** — and writes a positive `REVERSAL` per line back into the same bin; the issue stops counting against its requisition. A reason is required either way.\n\nThis is not how material that went to site comes back: a physical return is a material return (`POST /projects/{projectId}/material-returns`). An issue that material has been returned against cannot be reversed (`MATERIAL_ISSUE_HAS_RETURNS`).","operationId":"cancel","parameters":[{"name":"materialIssueId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelMaterialIssueDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialIssueDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material issue in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`MATERIAL_ISSUE_HAS_RETURNS`: posted returns exist against the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Cancel or reverse a material issue","tags":["Material Issues"]}},"/api/material-issues/{materialIssueId}/lines":{"get":{"description":"Each line carries its requisition line’s approved quantity, what other posted issues have already drawn on it, and its cost provenance (budget line, BOQ item, cost centre) joined from the requisition.","operationId":"listLines","parameters":[{"name":"materialIssueId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the issue’s lines.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MaterialIssueLineDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material issue in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List an issue’s lines","tags":["Material Issues"]},"post":{"description":"Names the requisition line (of this issue’s requisition), a stock-controlled item, the bin inside the issue’s store (omit for unbinned stock) and a quantity in the item’s base unit. Stock is not checked until posting, so a draft never holds stock against anyone.","operationId":"createLine","parameters":[{"name":"materialIssueId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMaterialIssueLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialIssueLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe requisition line is not on this issue’s requisition, or the quantity is not a positive decimal string."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material issue, stock item or bin in this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The issue is posted or cancelled, the item is not stock-controlled, or the bin is inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a line to a draft issue","tags":["Material Issues"]}},"/api/material-issues/{materialIssueId}/lines/{lineId}":{"patch":{"description":"Quantity, bin, notes and order. The item and the requisition line are the line’s identity — remove it and add another to change them.","operationId":"updateLine","parameters":[{"name":"materialIssueId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMaterialIssueLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialIssueLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material issue, line or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The issue is posted or cancelled, or the bin is inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft issue’s line","tags":["Material Issues"]},"delete":{"description":"Only while the issue is a draft.","operationId":"removeLine","parameters":[{"name":"materialIssueId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material issue or line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The issue is posted or cancelled and cannot be changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from a draft issue","tags":["Material Issues"]}},"/api/projects/{projectId}/material-issues":{"post":{"description":"Opens a **draft** against an APPROVED requisition of this project, drawing from one store, optionally with its lines. The project and organization come from the path and the requisition, never the body.\n\nA draft releases nothing and holds no stock; posting it is the act that matters. Header and lines are written together or not at all.","operationId":"create","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMaterialIssueDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialIssueDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nA line’s requisition line is not on the requisition, or a quantity is not a positive decimal string."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project, requisition (in this project), store, receiver, stock item or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The requisition is not APPROVED, the store, bin or receiver is inactive, an item is not stock-controlled, or you have no membership to record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Prepare a material issue","tags":["Material Issues"]},"get":{"description":"Every issue on one project, newest first, with the same filters as `GET /material-issues`. The project is resolved first, so another organization’s project is a 404 rather than an empty page.","operationId":"listForProject","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","POSTED","CANCELLED"]}},{"name":"requisitionId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"receiverMembershipId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"issuedByMembershipId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"postedFrom","required":false,"in":"query","description":"Earliest `postedAt`, **inclusive**. An ISO 8601 instant with an explicit offset.","schema":{"example":"2026-09-01T00:00:00Z","type":"string"}},{"name":"postedTo","required":false,"in":"query","description":"End of the `postedAt` window, **exclusive**.","schema":{"example":"2026-10-01T00:00:00Z","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of material issues.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MaterialIssueDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s material issues","tags":["Material Issues"]}},"/api/requisitions/{requisitionId}/issuing":{"get":{"description":"Per requisition line: approved quantity, quantity issued by POSTED issues, and what remains — exact decimal strings summed in PostgreSQL — with the line’s cost provenance. Drafts and cancelled issues do not count.\n\nAvailable stock is read from `GET /stock-balances?groupBy=location`; posting re-checks it authoritatively.","operationId":"issuing","parameters":[{"name":"requisitionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RequisitionIssuingLineDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"What has been issued against a requisition","tags":["Material Issues"]}},"/api/stock-transfers":{"get":{"description":"Every transfer in the organization, newest first. Filterable by `status`, `projectId`, `sourceStoreId`, `destinationStoreId` and `stockItemId`.\n\n`status=DISPATCHED` is **what is in transit right now**: goods that left their source and have not been received. The same stock shows in `GET /stock-balances?groupBy=location` as the source store’s `TRANSIT` location.","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","description":"`DISPATCHED` is every transfer whose goods are in transit right now.","schema":{"type":"string","enum":["DRAFT","DISPATCHED","RECEIVED","CANCELLED"]}},{"name":"projectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"sourceStoreId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"destinationStoreId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"stockItemId","required":false,"in":"query","description":"Only transfers with at least one line moving this item.","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of stock transfers.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockTransferDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List stock transfers","tags":["Stock Transfers"]}},"/api/stock-transfers/{stockTransferId}":{"get":{"description":"Who prepared, dispatched and received it, from which store to which, and when. The ledger rows it wrote are `GET /stock-movements?stockTransferId=…`. A transfer of another organization returns 404.","operationId":"findOne","parameters":[{"name":"stockTransferId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransferDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock transfer in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a stock transfer","tags":["Stock Transfers"]},"patch":{"description":"Purpose, notes — and the stores, while the transfer has no lines. The project cannot change. A **dispatched transfer is immutable**.","operationId":"update","parameters":[{"name":"stockTransferId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStockTransferDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransferDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock transfer or store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The transfer is not a draft, a store has lines drawn on it, a store is inactive, or a store is another project’s site store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft stock transfer","tags":["Stock Transfers"]}},"/api/stock-transfers/{stockTransferId}/dispatch":{"post":{"description":"Releases the goods into transit. Per line, writes a negative `TRANSFER` out of the source bin (`SOURCE_OUT`) and a positive one into the source store’s `TRANSIT` location (`TRANSIT_IN`), and records you as the dispatcher. The item’s total is unchanged; the stock is now on the road.\n\n**Negative stock is impossible.** Each source (store, bin, item) must hold what the transfer takes, checked in PostgreSQL under the same lock a material issue takes on that position — so a transfer and an issue racing for the last bag cannot both succeed. A line draws only on its own bin.\n\nBoth stores must be active and central or this project’s, every bin active, and every item stock-controlled. Any refusal leaves the transfer a draft with nothing written. Dispatching an already-dispatched transfer returns it unchanged.","operationId":"dispatch","parameters":[{"name":"stockTransferId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransferDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock transfer in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`INSUFFICIENT_STOCK`, `STOCK_TRANSFER_SOURCE_INACTIVE`, `STOCK_TRANSFER_DESTINATION_INACTIVE`, `STOCK_TRANSFER_STORE_NOT_IN_PROJECT`, `STORE_LOCATION_NOT_A_BIN`, `STOCK_ITEM_NOT_STOCK_CONTROLLED`, `EMPTY_STOCK_TRANSFER`, or the transfer is cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Dispatch a stock transfer","tags":["Stock Transfers"]}},"/api/stock-transfers/{stockTransferId}/receive":{"post":{"description":"Confirms the goods arrived. Per line, writes a negative `TRANSFER` out of transit (`TRANSIT_OUT`) and a positive one into the destination bin (`DESTINATION_IN`), and records you as the receiver.\n\n**Receipt is exact**: every line arrives as dispatched. Short, damaged or lost goods are not recorded here — that is the returns and adjustments stage.\n\nThe destination store and bins must be active. One deactivated while the goods were on the road refuses the receipt (`STOCK_TRANSFER_DESTINATION_INACTIVE`) and the goods stay in transit until it is reactivated. Receiving an already-received transfer returns it unchanged.","operationId":"receive","parameters":[{"name":"stockTransferId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransferDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock transfer in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`STOCK_TRANSFER_DESTINATION_INACTIVE`, or the transfer is a draft or cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Receive a dispatched stock transfer","tags":["Stock Transfers"]}},"/api/stock-transfers/{stockTransferId}/cancel":{"post":{"description":"Discards a **draft**; nothing moved. A reason is required.\n\nA **dispatched** transfer cannot be cancelled — its goods are on the road, and cancelling would record them back on the source shelf without any stock event. Receive it, then transfer the goods back if they should not have gone.","operationId":"cancel","parameters":[{"name":"stockTransferId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelStockTransferDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransferDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock transfer in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The transfer has been dispatched or received.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Cancel a draft stock transfer","tags":["Stock Transfers"]}},"/api/stock-transfers/{stockTransferId}/lines":{"get":{"description":"Each line names its item, the bin it leaves and the bin it goes into, and the quantity in the item’s base unit.","operationId":"listLines","parameters":[{"name":"stockTransferId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the transfer’s lines.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockTransferLineDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock transfer in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a transfer’s lines","tags":["Stock Transfers"]},"post":{"description":"Names a stock-controlled item, the bin inside the source store it leaves (omit for unbinned stock), the bin inside the destination store it goes into (omit for none), and a quantity in the item’s base unit. Within one store the two bins must differ. Stock is not checked until dispatch, so a draft never holds stock against anyone.","operationId":"createLine","parameters":[{"name":"stockTransferId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStockTransferLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransferLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe source and destination are the same position, or the quantity is not a positive decimal string."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock transfer, stock item or bin in that store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The transfer is not a draft, the item is not stock-controlled, or a bin is inactive or not a bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a line to a draft transfer","tags":["Stock Transfers"]}},"/api/stock-transfers/{stockTransferId}/lines/{lineId}":{"patch":{"description":"Quantity, either bin, notes and order. The item is the line’s identity — remove it and add another to change it.","operationId":"updateLine","parameters":[{"name":"stockTransferId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStockTransferLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransferLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock transfer, line or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The transfer is not a draft, or a bin is inactive or not a bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft transfer’s line","tags":["Stock Transfers"]},"delete":{"description":"Only while the transfer is a draft.","operationId":"removeLine","parameters":[{"name":"stockTransferId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock transfer or line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The transfer is not a draft and cannot be changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from a draft transfer","tags":["Stock Transfers"]}},"/api/projects/{projectId}/stock-transfers":{"post":{"description":"Opens a **draft** moving stock from one store to another on behalf of this project, optionally with its lines. Each store must be a central store or this project’s own site store — a transfer straight from one project’s site to another’s is refused; route it through a central store. The two stores may be the same, to move stock between its bins.\n\nA draft moves nothing and holds no stock; dispatching and receiving it are the acts that matter. Header and lines are written together or not at all.","operationId":"create","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStockTransferDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransferDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nA line’s source and destination are the same position, or a quantity is not a positive decimal string."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project, store, stock item or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A store is inactive or another project’s site store, a bin is inactive or not a bin, an item is not stock-controlled, or you have no membership to record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Prepare a stock transfer","tags":["Stock Transfers"]},"get":{"description":"Every transfer on one project, newest first, with the same filters as `GET /stock-transfers`. The project is resolved first, so another organization’s project is a 404 rather than an empty page.","operationId":"listForProject","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","description":"`DISPATCHED` is every transfer whose goods are in transit right now.","schema":{"type":"string","enum":["DRAFT","DISPATCHED","RECEIVED","CANCELLED"]}},{"name":"sourceStoreId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"destinationStoreId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"stockItemId","required":false,"in":"query","description":"Only transfers with at least one line moving this item.","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of stock transfers.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockTransferDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s stock transfers","tags":["Stock Transfers"]}},"/api/material-returns":{"get":{"description":"Every return in the organization, newest first. Filterable by `status`, `projectId`, `materialIssueId`, `storeId` and a half-open `postedFrom`/`postedTo` window.","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","POSTED","CANCELLED"]}},{"name":"projectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"materialIssueId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"postedFrom","required":false,"in":"query","description":"Earliest `postedAt`, **inclusive**. An ISO 8601 instant with an explicit offset.","schema":{"example":"2026-09-01T00:00:00Z","type":"string"}},{"name":"postedTo","required":false,"in":"query","description":"End of the `postedAt` window, **exclusive**.","schema":{"example":"2026-10-01T00:00:00Z","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of material returns.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MaterialReturnDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List material returns","tags":["Material Returns"]}},"/api/material-returns/{materialReturnId}":{"get":{"description":"What came back, from which issue, into which store, who brought it and who took it in. A return of another organization returns 404.","operationId":"findOne","parameters":[{"name":"materialReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialReturnDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material return in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a material return","tags":["Material Returns"]},"patch":{"description":"The reason, returner, notes — and the store, while the return has no lines. The issue is the return’s authority and cannot change. A **posted return is immutable**.","operationId":"update","parameters":[{"name":"materialReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMaterialReturnDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialReturnDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material return, store or member.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The return is posted or cancelled, the store has lines, or the store is inactive or another project’s site store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft material return","tags":["Material Returns"]}},"/api/material-returns/{materialReturnId}/post":{"post":{"description":"Takes the goods back in: writes one positive `RETURN` movement per line into its bin and records you as the receiver.\n\n**The issue caps the quantity.** Across every posted return, no more of an issue line may come back than it released — checked in PostgreSQL under a lock on the issue lines, so two returns racing for one line cannot both succeed. A return never reopens the requisition.\n\nThe issue must still be POSTED, the returner an active member, the store active and central or this project’s own, and every bin an active bin — never transit. Any refusal leaves the return a draft with nothing written. Posting an already-posted return returns it unchanged.","operationId":"post","parameters":[{"name":"materialReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialReturnDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material return in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`RETURNED_QUANTITY_EXCEEDED`, `MATERIAL_ISSUE_NOT_POSTED`, `MATERIAL_RETURN_RETURNED_BY_REQUIRED`, `MATERIAL_RETURN_DESTINATION_INACTIVE`, `STORE_LOCATION_NOT_A_BIN`, `EMPTY_MATERIAL_RETURN`, or the return is cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Post a material return","tags":["Material Returns"]}},"/api/material-returns/{materialReturnId}/cancel":{"post":{"description":"Cancelling a **draft** discards it. Cancelling a **posted** return states it was **recorded in error — the goods never came back** — and writes a negative `REVERSAL` per line out of the same bin; refused with `MATERIAL_RETURN_REVERSAL_INSUFFICIENT_STOCK` if that stock has since left again. A reason is required either way.","operationId":"cancel","parameters":[{"name":"materialReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelMaterialReturnDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialReturnDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material return in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The stock the return brought back has since left again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Cancel or reverse a material return","tags":["Material Returns"]}},"/api/material-returns/{materialReturnId}/lines":{"get":{"description":"Each line carries what its issue line released, what other posted returns have already brought back, and the cost provenance joined through the issue’s requisition line.","operationId":"listLines","parameters":[{"name":"materialReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the return’s lines.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MaterialReturnLineDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material return in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a return’s lines","tags":["Material Returns"]},"post":{"description":"Names a line of the return’s issue, the bin inside the return’s store (omit for unbinned stock; never transit) and a quantity in the item’s base unit. The item is the issue line’s. The cap is checked at posting.","operationId":"createLine","parameters":[{"name":"materialReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMaterialReturnLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialReturnLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe issue line is not on this return’s issue, or the quantity is not a positive decimal string."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material return or bin in this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The return is not a draft, it already has a line for that issue line, or the bin is transit or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a line to a draft return","tags":["Material Returns"]}},"/api/material-returns/{materialReturnId}/lines/{lineId}":{"patch":{"description":"Quantity, bin, notes and order. The issue line is the line’s identity.","operationId":"updateLine","parameters":[{"name":"materialReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMaterialReturnLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialReturnLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material return, line or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The return is not a draft, or the bin is transit or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft return’s line","tags":["Material Returns"]},"delete":{"description":"Only while the return is a draft.","operationId":"removeLine","parameters":[{"name":"materialReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material return or line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The return is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from a draft return","tags":["Material Returns"]}},"/api/projects/{projectId}/material-returns":{"post":{"description":"Opens a **draft** return of unused material against a POSTED material issue of this project, into a central store or this project’s own site store, optionally with its lines. Header and lines are written together or not at all. A draft moves nothing.","operationId":"create","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMaterialReturnDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialReturnDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nA line’s issue line is not on the issue, or a quantity is not a positive decimal string."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project, material issue (in this project), store, member or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The issue is not POSTED, the store is inactive or another project’s site store, a bin is transit or inactive, or you have no membership to record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Prepare a material return","tags":["Material Returns"]},"get":{"description":"Every return on one project, newest first, with the same filters as `GET /material-returns`. Another organization’s project is a 404 rather than an empty page.","operationId":"listForProject","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","POSTED","CANCELLED"]}},{"name":"materialIssueId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"postedFrom","required":false,"in":"query","description":"Earliest `postedAt`, **inclusive**. An ISO 8601 instant with an explicit offset.","schema":{"example":"2026-09-01T00:00:00Z","type":"string"}},{"name":"postedTo","required":false,"in":"query","description":"End of the `postedAt` window, **exclusive**.","schema":{"example":"2026-10-01T00:00:00Z","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of material returns.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MaterialReturnDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s material returns","tags":["Material Returns"]}},"/api/material-issues/{materialIssueId}/returnable":{"get":{"description":"Per issue line: what it released, what POSTED returns have brought back, and what may still come back — exact decimal strings summed in PostgreSQL — with its cost provenance. Drafts and cancelled returns do not count. Posting re-checks authoritatively.","operationId":"returnable","parameters":[{"name":"materialIssueId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MaterialIssueReturnableLineDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such material issue in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"What may still come back against an issue","tags":["Material Returns"]}},"/api/supplier-returns":{"get":{"description":"Every return in the organization, newest first. Filterable by `status`, `projectId`, `goodsReceiptId`, `purchaseOrderId`, `supplierId`, `storeId` and a half-open `postedFrom`/`postedTo` window.","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","POSTED","CANCELLED"]}},{"name":"projectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"goodsReceiptId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"purchaseOrderId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"supplierId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"postedFrom","required":false,"in":"query","description":"Earliest `postedAt`, **inclusive**.","schema":{"example":"2026-09-01T00:00:00Z","type":"string"}},{"name":"postedTo","required":false,"in":"query","description":"End of the `postedAt` window, **exclusive**.","schema":{"example":"2026-10-01T00:00:00Z","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of supplier returns.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SupplierReturnDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List supplier returns","tags":["Supplier Returns"]}},"/api/supplier-returns/{supplierReturnId}":{"get":{"description":"What went back to which supplier, against which receipt and order, from which store, and who released it. A return of another organization returns 404.","operationId":"findOne","parameters":[{"name":"supplierReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierReturnDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier return in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a supplier return","tags":["Supplier Returns"]},"patch":{"description":"The reason, supplier reference, notes — and the store, while the return has no lines. The receipt is the return’s authority and cannot change. A **posted return is immutable**.","operationId":"update","parameters":[{"name":"supplierReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSupplierReturnDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierReturnDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier return or store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The return is posted or cancelled, the store has lines, or the store is inactive or another project’s site store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft supplier return","tags":["Supplier Returns"]}},"/api/supplier-returns/{supplierReturnId}/post":{"post":{"description":"Sends the goods back: writes one negative `SUPPLIER_RETURN` movement per line out of its bin and records you as the poster.\n\n**Negative stock is impossible.** Each (store, bin, item) must hold what the return takes, checked in PostgreSQL under the same per-position lock an issue and a transfer take.\n\n**The receipt caps the quantity.** Across every posted supplier return, no more of a receipt line may go back than it received — checked under a lock on the receipt lines, so two returns racing for one line cannot both succeed. The order’s received quantity is unchanged.\n\nThe receipt must still be POSTED, the store active and central or this project’s own, and every bin an active bin — never transit. Any refusal leaves the return a draft with nothing written. Posting an already-posted return returns it unchanged.","operationId":"post","parameters":[{"name":"supplierReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierReturnDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier return in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`INSUFFICIENT_STOCK`, `SUPPLIER_RETURNED_QUANTITY_EXCEEDED`, `GOODS_RECEIPT_NOT_POSTED`, `SUPPLIER_RETURN_SOURCE_INACTIVE`, `STORE_LOCATION_NOT_A_BIN`, `STOCK_ITEM_NOT_STOCK_CONTROLLED`, `EMPTY_SUPPLIER_RETURN`, or the return is cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Post a supplier return","tags":["Supplier Returns"]}},"/api/supplier-returns/{supplierReturnId}/cancel":{"post":{"description":"Cancelling a **draft** discards it. Cancelling a **posted** return states it was **recorded in error — the goods never went back** — and writes a positive `REVERSAL` per line into the same bin; the return stops counting against its receipt. A reason is required either way.","operationId":"cancel","parameters":[{"name":"supplierReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSupplierReturnDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierReturnDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier return in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Cancel or reverse a supplier return","tags":["Supplier Returns"]}},"/api/supplier-returns/{supplierReturnId}/lines":{"get":{"description":"Each line carries what its receipt line received and what other posted supplier returns have already sent back.","operationId":"listLines","parameters":[{"name":"supplierReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the return’s lines.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SupplierReturnLineDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier return in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a return’s lines","tags":["Supplier Returns"]},"post":{"description":"Names a line of the return’s receipt that moved stock, the bin inside the return’s store the goods leave from (omit for unbinned stock; never transit) and a quantity in the item’s base unit. The item is the one the receipt line put into stock. Stock and the cap are checked at posting.","operationId":"createLine","parameters":[{"name":"supplierReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSupplierReturnLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierReturnLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe receipt line is not on this return’s receipt, or the quantity is not a positive decimal string."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier return or bin in this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The return is not a draft, it already has a line for that receipt line, the receipt line moved no stock, or the bin is transit or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a line to a draft return","tags":["Supplier Returns"]}},"/api/supplier-returns/{supplierReturnId}/lines/{lineId}":{"patch":{"description":"Quantity, bin, notes and order. The receipt line is the line’s identity.","operationId":"updateLine","parameters":[{"name":"supplierReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSupplierReturnLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierReturnLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier return, line or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The return is not a draft, or the bin is transit or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft return’s line","tags":["Supplier Returns"]},"delete":{"description":"Only while the return is a draft.","operationId":"removeLine","parameters":[{"name":"supplierReturnId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier return or line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The return is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from a draft return","tags":["Supplier Returns"]}},"/api/projects/{projectId}/supplier-returns":{"post":{"description":"Opens a **draft** return of goods to their supplier against a POSTED goods receipt of this project, from a central store or this project’s own site store, optionally with its lines. Header and lines are written together or not at all. A draft moves nothing and reserves no stock.","operationId":"create","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSupplierReturnDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierReturnDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nA line’s receipt line is not on the receipt, or a quantity is not a positive decimal string."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project, goods receipt (in this project), store or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The receipt is not POSTED, a receipt line moved no stock, the store is inactive or another project’s site store, a bin is transit or inactive, or you have no membership to record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Prepare a supplier return","tags":["Supplier Returns"]},"get":{"description":"Every return on one project, newest first, with the same filters as `GET /supplier-returns`. Another organization’s project is a 404 rather than an empty page.","operationId":"listForProject","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","POSTED","CANCELLED"]}},{"name":"goodsReceiptId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"purchaseOrderId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"supplierId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"postedFrom","required":false,"in":"query","description":"Earliest `postedAt`, **inclusive**.","schema":{"example":"2026-09-01T00:00:00Z","type":"string"}},{"name":"postedTo","required":false,"in":"query","description":"End of the `postedAt` window, **exclusive**.","schema":{"example":"2026-10-01T00:00:00Z","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of supplier returns.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SupplierReturnDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s supplier returns","tags":["Supplier Returns"]}},"/api/goods-receipts/{goodsReceiptId}/returnable":{"get":{"description":"Per receipt line that moved stock: what it received, what POSTED supplier returns have sent back, and what may still go back — exact decimal strings summed in PostgreSQL. Service lines never entered a store and do not appear. Posting re-checks authoritatively.","operationId":"returnable","parameters":[{"name":"goodsReceiptId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GoodsReceiptReturnableLineDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such goods receipt in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"What may still go back against a receipt","tags":["Supplier Returns"]}},"/api/supplier-invoices":{"post":{"description":"Opens a **draft** invoice against an ISSUED or CLOSED purchase order, optionally with its lines.\n\nThe order is the only thing named: project, supplier and currency follow from it. `dueDate` defaults to the invoice date plus the supplier’s payment terms.\n\n`supplierInvoiceNumber` is normalised (spaces removed, upper-cased) and must be unique per supplier among invoices that are not cancelled — a duplicate is `409 DUPLICATE_SUPPLIER_INVOICE`.\n\nLine `unitPrice` defaults to the order’s price; key the supplier’s price when it differs and the match will show it.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSupplierInvoiceDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceWithLinesDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe order is not ISSUED or CLOSED, or a line names an item not on it."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"This supplier already has a live invoice with that number.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Record a supplier invoice","tags":["Supplier Invoices"]},"get":{"description":"Newest first. Filter by `status`, `purchaseOrderId`, `supplierId` or `projectId`; `search` matches the firm’s number or the supplier’s.","operationId":"list","parameters":[{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","SUBMITTED","ON_HOLD","APPROVED","CANCELLED"]}},{"name":"purchaseOrderId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"supplierId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"projectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Matches the firm's number or the supplier's, case-insensitively.","schema":{"maxLength":64,"type":"string"}}],"responses":{"200":{"description":"A page of supplier invoices.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SupplierInvoiceDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List supplier invoices","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}":{"get":{"operationId":"findOne","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceWithLinesDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a supplier invoice with its lines","tags":["Supplier Invoices"]},"patch":{"description":"**DRAFT only.** The order cannot change.","operationId":"update","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSupplierInvoiceDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The invoice is not a draft, or the number duplicates another.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Edit a draft supplier invoice","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}/lines":{"get":{"operationId":"listLines","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SupplierInvoiceLineDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List an invoice’s lines","tags":["Supplier Invoices"]},"post":{"description":"The order line must be on the invoice’s own order, at most once per invoice. Unit comes from the order line.","operationId":"createLine","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSupplierInvoiceLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The invoice is not a draft, or already bills that item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a line to a draft invoice","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}/lines/{lineId}":{"patch":{"operationId":"updateLine","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSupplierInvoiceLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such invoice or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The invoice is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Edit a line on a draft invoice","tags":["Supplier Invoices"]},"delete":{"operationId":"removeLine","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The line was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such invoice or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The invoice is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from a draft invoice","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}/match":{"get":{"description":"Each line against its order line (price) and its receipts (quantity: posted receipts less posted supplier returns, less what the line’s other live invoices claim).\n\nLive until approval; after that, the snapshot recorded when it was approved (`snapshot: true`). A quantity beyond what was received is always an EXCEPTION; a price difference is WITHIN_TOLERANCE when inside the organization’s tolerances.","operationId":"match","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceMatchDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Three-way match an invoice","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}/submit":{"post":{"description":"Locks it against editing. Refused if it has no lines, its order is no longer ISSUED or CLOSED, or it would take any order line past its **ordered** quantity across all live invoices (`409 INVOICED_QUANTITY_EXCEEDS_ORDERED`) — invoicing beyond the order is never a variance to approve. Idempotent.","operationId":"submit","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Not a draft, empty, or beyond the ordered quantity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Submit an invoice for approval","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}/approve":{"post":{"description":"Accepts that the firm owes it: the amount now counts in budget actuals. The match is computed at this moment and recorded with the approval.\n\n- Only a MATCHED or WITHIN_TOLERANCE invoice is approved here. An EXCEPTION is `409 SUPPLIER_INVOICE_MATCH_EXCEPTION` — hold it, or use `approve-variance`.\n- The member who **recorded** the invoice can never approve it (`403 SUPPLIER_INVOICE_SELF_APPROVAL`).\n\nIdempotent.","operationId":"approve","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\nYou recorded this invoice."},"404":{"description":"No such invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The invoice is not SUBMITTED, or does not match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Approve a submitted invoice","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}/approve-variance":{"post":{"description":"For an invoice whose match is an EXCEPTION — billing more than was received, or a price outside tolerance — that the firm has decided to pay anyway. Needs `supplier_invoice.approve_variance` as well as `supplier_invoice.approve`, and a `varianceReason`, which is recorded with the approval and the match snapshot.\n\nThe recorder can never approve (`403 SUPPLIER_INVOICE_SELF_APPROVAL`). Idempotent.","operationId":"approveVariance","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveSupplierInvoiceVarianceDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\nYou recorded this invoice."},"404":{"description":"No such invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The invoice is not SUBMITTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Approve an invoice that does not match","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}/hold":{"post":{"description":"Parks a disputed invoice with a reason — for the supplier to correct or explain. It keeps its claim on the order’s quantities while held. Idempotent.","operationId":"hold","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceReasonDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The invoice is not SUBMITTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Put a submitted invoice on hold","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}/release":{"post":{"description":"Back to SUBMITTED, awaiting a decision. Idempotent.","operationId":"release","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The invoice is not ON_HOLD.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Release a held invoice","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}/cancel":{"post":{"description":"Needs a reason. Cancelling an **APPROVED** invoice reverses it out of actuals and also needs `supplier_invoice.approve` (`403 CANCEL_APPROVED_INVOICE_NOT_PERMITTED`). A cancelled invoice’s number may be keyed again. Idempotent.","operationId":"cancel","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceReasonDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInvoiceDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Cancel an invoice","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}/attachments":{"post":{"description":"The supplier’s own invoice, a tax invoice, a statement. JPEG, PNG, WebP or PDF, checked by content. Allowed at every status but CANCELLED (`409 SUPPLIER_INVOICE_ATTACHMENT_LOCKED`) — the original often follows a scan.","operationId":"attach","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"caption":{"type":"string"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The supplier invoice is cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Attach a supporting document to a supplier invoice","tags":["Supplier Invoices"]},"get":{"operationId":"listAttachments","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a supplier invoice’s supporting documents","tags":["Supplier Invoices"]}},"/api/supplier-invoices/{supplierInvoiceId}/attachments/{attachmentId}":{"delete":{"description":"**DRAFT only.** Once submitted, an invoice’s documents are what it was matched and approved against and are kept (`409 SUPPLIER_INVOICE_ATTACHMENT_LOCKED`).","operationId":"removeAttachment","parameters":[{"name":"supplierInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"attachmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The document was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier invoice or document in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The supplier invoice is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a supporting document from a draft supplier invoice","tags":["Supplier Invoices"]}},"/api/projects/{projectId}/supplier-invoices":{"get":{"description":"The project is resolved first, so an id from another organization returns 404 rather than an empty page.","operationId":"listForProject","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","SUBMITTED","ON_HOLD","APPROVED","CANCELLED"]}},{"name":"purchaseOrderId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"supplierId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Matches the firm's number or the supplier's, case-insensitively.","schema":{"maxLength":64,"type":"string"}}],"responses":{"200":{"description":"A page of supplier invoices.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SupplierInvoiceDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s supplier invoices","tags":["Supplier Invoices"]}},"/api/purchase-orders/{purchaseOrderId}/invoicing":{"get":{"description":"Per line: ordered, received (net of returns), invoiced on approved invoices, pending on submitted or held ones, and what may still be invoiced without an exception. `fullyInvoiced` is true when every line is approved up to its ordered quantity — the order has nothing left to bill, and may be closed.","operationId":"invoicing","parameters":[{"name":"purchaseOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderInvoicingDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such purchase order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"An order’s invoicing position","tags":["Supplier Invoices"]}},"/api/procurement-settings":{"get":{"description":"Readable by anyone who can view invoices, since a match is judged by these thresholds. Zero until changed.","operationId":"get","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementSettingsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get the invoice matching tolerances","tags":["Supplier Invoices"]},"patch":{"description":"A price difference is tolerated when within `priceTolerancePercent` of the order price, or when the line’s variance amount is within `amountTolerance`. Quantities are never tolerated. Applies to invoices approved from now on; approved invoices keep the tolerances recorded with them.","operationId":"update","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProcurementSettingsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementSettingsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Change the invoice matching tolerances","tags":["Supplier Invoices"]}},"/api/supplier-payments":{"post":{"description":"A **draft** payment to one supplier, optionally with its allocations to approved invoices. Nothing is settled until it is posted.\n\nA BANK_TRANSFER must name one of the supplier’s bank accounts; it must be VERIFIED by the time the payment is posted. Every allocated invoice must be APPROVED, the supplier’s, and in the payment’s currency.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSupplierPaymentDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierPaymentWithAllocationsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe bank account is missing, retired or another supplier’s, or an invoice is not payable."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Prepare a supplier payment","tags":["Supplier Payments"]},"get":{"description":"Newest payment date first. Filter by `status` or `supplierId`; `search` matches the payment number or bank reference.","operationId":"list","parameters":[{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","POSTED","VOIDED"]}},{"name":"supplierId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Matches the payment number or the bank reference.","schema":{"maxLength":100,"type":"string"}}],"responses":{"200":{"description":"A page of supplier payments.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SupplierPaymentDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List supplier payments","tags":["Supplier Payments"]}},"/api/supplier-payments/{supplierPaymentId}":{"get":{"operationId":"findOne","parameters":[{"name":"supplierPaymentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierPaymentWithAllocationsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such payment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a supplier payment with its allocations","tags":["Supplier Payments"]},"patch":{"description":"**DRAFT only.** The supplier cannot change.","operationId":"update","parameters":[{"name":"supplierPaymentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSupplierPaymentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierPaymentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such payment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The payment is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Edit a draft payment","tags":["Supplier Payments"]}},"/api/supplier-payments/{supplierPaymentId}/allocations":{"post":{"description":"The invoice must be APPROVED, this supplier’s, and in the payment’s currency. Overpayment is checked when the payment is posted, against every payment posted by then.","operationId":"addAllocation","parameters":[{"name":"supplierPaymentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSupplierPaymentAllocationDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SupplierPaymentAllocationDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such payment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The payment is not a draft, or already settles that invoice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Allocate a draft payment to an invoice","tags":["Supplier Payments"]}},"/api/supplier-payments/{supplierPaymentId}/allocations/{allocationId}":{"patch":{"operationId":"updateAllocation","parameters":[{"name":"supplierPaymentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"allocationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSupplierPaymentAllocationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SupplierPaymentAllocationDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such payment or allocation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The payment is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Change an allocation on a draft payment","tags":["Supplier Payments"]},"delete":{"operationId":"removeAllocation","parameters":[{"name":"supplierPaymentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"allocationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The allocation was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such payment or allocation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The payment is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove an allocation from a draft payment","tags":["Supplier Payments"]}},"/api/supplier-payments/{supplierPaymentId}/post":{"post":{"description":"Records that the money left the firm and settles the allocated invoices. Refused when:\n\n- it settles nothing (`409 EMPTY_SUPPLIER_PAYMENT`) or its allocations do not equal its amount exactly (`409 SUPPLIER_PAYMENT_UNBALANCED`);\n- a BANK_TRANSFER’s account is not VERIFIED (`409 PAYMENT_BANK_ACCOUNT_NOT_VERIFIED`);\n- an invoice is no longer APPROVED or is in another currency (`409 INVOICE_NOT_PAYABLE`), or would be overpaid (`409 SUPPLIER_INVOICE_OVERPAYMENT`);\n- you approved any invoice it settles (`403 SUPPLIER_PAYMENT_POSTED_BY_INVOICE_APPROVER`).\n\nIdempotent.","operationId":"post","parameters":[{"name":"supplierPaymentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierPaymentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\nYou approved an invoice this payment settles."},"404":{"description":"No such payment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Not a draft, unbalanced, an unverified account, or an overpayment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Post a payment","tags":["Supplier Payments"]}},"/api/supplier-payments/{supplierPaymentId}/void":{"post":{"description":"Needs a reason. Voiding a draft discards it; voiding a posted payment records that it did not happen after all, and the invoices it settled become outstanding again. Terminal and idempotent.","operationId":"void","parameters":[{"name":"supplierPaymentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoidSupplierPaymentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierPaymentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such payment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Void a payment","tags":["Supplier Payments"]}},"/api/supplier-payments/{supplierPaymentId}/attachments":{"post":{"description":"Transfer advice, a cheque copy, the supplier’s receipt. JPEG, PNG, WebP or PDF, checked by content. Allowed on DRAFT and POSTED payments — remittance advice often arrives after posting — but not on a VOIDED one (`409 SUPPLIER_PAYMENT_ATTACHMENT_LOCKED`).","operationId":"attach","parameters":[{"name":"supplierPaymentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"caption":{"type":"string"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such payment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The payment is voided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Attach a supporting document to a payment","tags":["Supplier Payments"]},"get":{"operationId":"listAttachments","parameters":[{"name":"supplierPaymentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such payment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a payment’s supporting documents","tags":["Supplier Payments"]}},"/api/supplier-payments/{supplierPaymentId}/attachments/{attachmentId}":{"delete":{"description":"**DRAFT only.** Once posted, a payment’s documents are the evidence it rests on and are kept (`409 SUPPLIER_PAYMENT_ATTACHMENT_LOCKED`).","operationId":"removeAttachment","parameters":[{"name":"supplierPaymentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"attachmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The document was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such payment or document in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The payment is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a supporting document from a draft payment","tags":["Supplier Payments"]}},"/api/suppliers/{supplierId}/statement":{"get":{"description":"Approved invoices (debit) and posted payments (credit), oldest first, with a running balance per currency. `from` brings everything earlier forward as an opening balance. Cancelled invoices and voided payments are not shown.","operationId":"statement","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"from","required":false,"in":"query","description":"Entries on or after this date. The opening balance carries everything before.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"Entries on or before this date.","schema":{"type":"string"}},{"name":"currency","required":false,"in":"query","description":"One currency only. Balances are always kept per currency.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierStatementDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"A supplier’s statement of account","tags":["Supplier Payments"]}},"/api/payables/aging":{"get":{"description":"What the firm owes on approved invoices, per supplier and currency, by days past due: current, 1–30, 31–60, 61–90, over 90. As at `asOf` (default today in the organization’s timezone): only invoices dated and payments posted on or before it count, so a past date reproduces the position as it was.","operationId":"aging","parameters":[{"name":"asOf","required":false,"in":"query","description":"Age as at this date. Defaults to today in the organization's timezone.","schema":{"type":"string"}},{"name":"supplierId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"projectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayablesAgingDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Payables aging","tags":["Supplier Payments"]}},"/api/rfqs":{"post":{"description":"A **draft** RFQ against an APPROVED requisition, optionally with lines (each a requisition line, at most its approved quantity) and invited suppliers (ACTIVE). The project follows from the requisition.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRfqDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe requisition is not approved, a line is not on it or exceeds it, or a supplier is inactive."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Open a request for quotation","tags":["Sourcing"]},"get":{"description":"Newest first. Filter by `status`, `projectId` or `requisitionId`; `search` matches the number or title.","operationId":"list","parameters":[{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","ISSUED","CLOSED","AWARDED","CANCELLED"]}},{"name":"projectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"requisitionId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Matches the RFQ number or title.","schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"description":"A page of requests for quotation.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RfqDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List requests for quotation","tags":["Sourcing"]}},"/api/rfqs/{rfqId}":{"get":{"operationId":"findOne","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get an RFQ with its lines and invited suppliers","tags":["Sourcing"]},"patch":{"description":"While DRAFT or ISSUED.","operationId":"update","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRfqDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The RFQ is closed, awarded or cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Edit an RFQ’s title, closing date or notes","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/lines":{"post":{"description":"Quantity defaults to the requisition line’s and may be less, never more.","operationId":"addLine","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRfqLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The RFQ is not a draft, or already has that line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a requisition line to a draft RFQ","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/lines/{lineId}":{"patch":{"operationId":"updateLine","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRfqLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The RFQ is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Change a draft RFQ line’s quantity","tags":["Sourcing"]},"delete":{"operationId":"removeLine","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The line was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ or line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The RFQ is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from a draft RFQ","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/suppliers":{"post":{"description":"While DRAFT or ISSUED. The supplier must be ACTIVE.","operationId":"invite","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteRfqSupplierDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Bidding is over, or the supplier is already invited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Invite a supplier to quote","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/suppliers/{supplierId}":{"delete":{"description":"Only for a supplier who has not quoted.","operationId":"uninvite","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The invitation was withdrawn."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ or invitation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Bidding is over, or the supplier has quoted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Withdraw an invitation","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/issue":{"post":{"description":"Records that it went to the invited suppliers (nothing is sent by the system) and opens it for quotations. Needs at least one line and one supplier, and a requisition still APPROVED. Idempotent.","operationId":"issue","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Not a draft, or no lines or suppliers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Issue an RFQ","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/close":{"post":{"description":"No quotation may be recorded or corrected after this, so the comparison an award is decided on cannot move. Idempotent.","operationId":"close","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The RFQ is not ISSUED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Close bidding","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/cancel":{"post":{"description":"Needs a reason. Not once awarded — cancel the draft orders it raised instead. Idempotent.","operationId":"cancel","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqReasonDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The RFQ is awarded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Cancel an RFQ","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/comparison":{"get":{"description":"Per line, every live quotation’s price with the cheapest valid one flagged; per quotation, its total, whether it quotes every line, and whether it is the cheapest complete offer. Lapsed offers (past `validUntil`, today in the organization’s timezone) are shown but flagged `expired`.","operationId":"comparison","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqComparisonDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Compare quotations","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/award":{"post":{"description":"Decides which quotation wins which line — lines may be split across suppliers, and left unawarded — and raises one **DRAFT purchase order per winning supplier**, at the quoted prices, through the ordinary purchase-order rules. The orders still need issuing.\n\n- The RFQ must be CLOSED.\n- Each awarded quotation must be RECEIVED, quote the line, and still be valid (`409 RFQ_AWARD_INVALID` when lapsed).\n- Choosing a quotation that is not the cheapest valid one for a line needs a `reason` (`400 RFQ_AWARD_REASON_REQUIRED`).","operationId":"award","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AwardRfqDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqAwardResultDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nAn award names a line or quotation not on this RFQ, or needs a reason."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The RFQ is not CLOSED, or a quotation is not awardable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Award an RFQ","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/quotations":{"get":{"operationId":"list","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/QuotationDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List an RFQ’s quotations, withdrawn ones included","tags":["Sourcing"]},"post":{"description":"While the RFQ is ISSUED. The supplier must be invited, and has at most one live quotation; lines must be on the RFQ, at least one.","operationId":"record","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateQuotationDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotationWithLinesDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The RFQ is not ISSUED, or the supplier already has a live quotation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Record a supplier’s quotation","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/quotations/{quotationId}":{"get":{"operationId":"findOne","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"quotationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotationWithLinesDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ or quotation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a quotation with its lines","tags":["Sourcing"]},"patch":{"description":"While the RFQ is ISSUED. `lines`, when sent, replaces them all.","operationId":"update","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"quotationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateQuotationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotationWithLinesDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ or quotation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The RFQ is not ISSUED, or the quotation is not live.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Correct a quotation","tags":["Sourcing"]}},"/api/rfqs/{rfqId}/quotations/{quotationId}/withdraw":{"post":{"description":"Needs a reason. Allowed until the award; a replacement may then be recorded while the RFQ is ISSUED.","operationId":"withdraw","parameters":[{"name":"rfqId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"quotationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawQuotationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotationWithLinesDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such RFQ or quotation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The RFQ is awarded or cancelled, or the quotation is not live.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Withdraw a quotation","tags":["Sourcing"]}},"/api/projects/{projectId}/rfqs":{"get":{"description":"The project is resolved first, so an id from another organization returns 404 rather than an empty page.","operationId":"list","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","ISSUED","CLOSED","AWARDED","CANCELLED"]}},{"name":"requisitionId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Matches the RFQ number or title.","schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"description":"A page of requests for quotation.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RfqDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s requests for quotation","tags":["Sourcing"]}},"/api/subcontracts":{"post":{"description":"A DRAFT agreement with an ACTIVE supplier typed SUBCONTRACTOR, optionally with its schedule of rates. Every item’s budget line must be on the same project. Nothing is committed until it is activated.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubcontractDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nThe project, supplier or a budget line is not valid for this subcontract."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Draft a subcontract","tags":["Subcontracts"]},"get":{"description":"Newest first. Filter by `status`, `projectId` or `supplierId`; `search` matches the number or title.","operationId":"list","parameters":[{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","ACTIVE","PRACTICALLY_COMPLETE","FINAL_ACCOUNT_CLOSED","TERMINATED"]}},{"name":"projectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"supplierId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Matches the number or title.","schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"description":"A page of subcontracts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SubcontractDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List subcontracts","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}":{"get":{"operationId":"findOne","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a subcontract with its schedule","tags":["Subcontracts"]},"patch":{"description":"**DRAFT only.** Supplier and project cannot change.","operationId":"update","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubcontractDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The subcontract is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Edit a draft subcontract’s terms","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/items":{"post":{"description":"**DRAFT only.** Once active, the schedule changes through variations.","operationId":"addItem","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractItemInputDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The subcontract is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add an item to a draft schedule","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/items/{itemId}":{"patch":{"operationId":"updateItem","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"itemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubcontractItemDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract or item in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The subcontract is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Edit an item of a draft schedule","tags":["Subcontracts"]},"delete":{"operationId":"removeItem","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"itemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"The item was removed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract or item in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The subcontract is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove an item from a draft schedule","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/activate":{"post":{"description":"The schedule becomes committed against its budget lines and the contract sum is recorded as the original. Needs at least one item and a supplier still ACTIVE and typed SUBCONTRACTOR. Idempotent.","operationId":"activate","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Not a draft, no items, or the supplier no longer qualifies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Activate a signed subcontract","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/practical-completion":{"post":{"description":"The works are handed over. Valuations continue, and may now release retention.","operationId":"practicalCompletion","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PracticalCompletionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The subcontract is not ACTIVE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Record practical completion","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/close-final-account":{"post":{"description":"Terminal. Refused while a valuation or variation is still undecided.","operationId":"closeFinalAccount","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Not practically complete, or documents still pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Close the final account","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/terminate":{"post":{"description":"Needs a reason. Only what was certified stays committed; the uncompleted balance returns to the budget, and any draft valuation is cancelled.","operationId":"terminate","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractReasonDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The subcontract is a draft or already closed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Terminate a subcontract","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/variations":{"get":{"operationId":"listVariations","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VariationDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a subcontract’s variations","tags":["Subcontracts"]},"post":{"description":"On an ACTIVE or PRACTICALLY_COMPLETE subcontract. Each line either changes an existing item’s quantity (`itemId`, signed `quantityChange`) or adds a new item (`description`, `unit`, `quantity`, `rate`, `budgetLineId`). Nothing changes until another member approves it.","operationId":"createVariation","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVariationDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The subcontract is not live.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Raise a variation","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/variations/{variationId}":{"get":{"operationId":"findVariation","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"variationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract or variation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a variation","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/variations/{variationId}/approve":{"post":{"description":"Applies it to the schedule: quantities change and new items are added, so the contract sum and the commitment move. Never by whoever raised it (`403 SUBCONTRACT_VARIATION_SELF_APPROVAL`); never reduces an item below what is already certified (`409 SUBCONTRACT_VARIATION_BELOW_CERTIFIED`). Idempotent.","operationId":"approveVariation","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"variationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideVariationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\nYou raised this variation."},"404":{"description":"No such subcontract or variation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Already decided, or it would undercut certified work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Approve a variation","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/variations/{variationId}/reject":{"post":{"operationId":"rejectVariation","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"variationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideVariationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\nYou raised this variation."},"404":{"description":"No such subcontract or variation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Already decided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Reject a variation","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/valuations":{"get":{"operationId":"listValuations","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ValuationDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a subcontract’s valuations","tags":["Subcontracts"]},"post":{"description":"One draft at a time. Every item starts at its last certified cumulative quantity; `lines` sets those that moved. Quantities are cumulative to date, never this period’s increment, and never beyond the item’s scheduled quantity.","operationId":"createValuation","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateValuationDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The subcontract is not live, or a draft already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Open a valuation","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/valuations/{valuationId}":{"get":{"description":"A draft’s figures are computed live; a certified one’s are the certificate’s snapshot (`certified: true`).","operationId":"findValuation","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"valuationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract or valuation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a valuation","tags":["Subcontracts"]},"patch":{"operationId":"updateValuation","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"valuationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateValuationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract or valuation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The valuation is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Re-measure a draft valuation","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/valuations/{valuationId}/cancel":{"post":{"operationId":"cancelValuation","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"valuationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubcontractReasonDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such subcontract or valuation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The valuation is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Cancel a draft valuation","tags":["Subcontracts"]}},"/api/subcontracts/{subcontractId}/valuations/{valuationId}/certify":{"post":{"description":"Freezes its figures and raises an **APPROVED supplier invoice** for the amount due, payable through the ordinary payments flow. Refused when:\n\n- you prepared it (`403 SUBCONTRACT_VALUATION_SELF_CERTIFICATION`);\n- any item is measured beyond the schedule (`SUBCONTRACT_VALUATION_EXCEEDS_SCHEDULE`);\n- retention release went down, or is released before practical completion;\n- nothing is due (`SUBCONTRACT_VALUATION_NOTHING_DUE`).\n\nIdempotent.","operationId":"certify","parameters":[{"name":"subcontractId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"valuationId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\nYou prepared this valuation."},"404":{"description":"No such subcontract or valuation in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Not a draft, or not certifiable as measured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Certify a valuation","tags":["Subcontracts"]}},"/api/projects/{projectId}/subcontracts":{"get":{"description":"The project is resolved first, so an id from another organization returns 404 rather than an empty page.","operationId":"list","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","ACTIVE","PRACTICALLY_COMPLETE","FINAL_ACCOUNT_CLOSED","TERMINATED"]}},{"name":"supplierId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Matches the number or title.","schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"description":"A page of subcontracts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SubcontractDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a project’s subcontracts","tags":["Subcontracts"]}},"/api/projects/{projectId}/subcontracts/budget-lines":{"get":{"description":"The lines of the project’s ACTIVE budget — empty when it has none — for the schedule-of-rates and variation pickers. Identifying fields only: no amounts, so `budget.view` is not needed and budget figures are not disclosed.","operationId":"budgetLines","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SubcontractBudgetLineOptionDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Budget lines a subcontract on this project can draw on","tags":["Subcontracts"]}},"/api/supplier-performance":{"get":{"description":"A page of suppliers (ACTIVE by default) with every measure, ordered by name. Filter by `supplierType` or `search`; `from`/`to` bound each measure’s own events. A measure with no events is `null` with `sampleSize` 0 — never 0% or 100%.","operationId":"list","parameters":[{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"from","required":false,"in":"query","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Defaults to ACTIVE suppliers.","schema":{"type":"string","enum":["ACTIVE","INACTIVE"]}},{"name":"supplierType","required":false,"in":"query","schema":{"type":"string","enum":["MATERIALS","SERVICES","SUBCONTRACTOR","PLANT_HIRE","CONSULTANT"]}},{"name":"search","required":false,"in":"query","description":"Matches the name or code.","schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"description":"A page of supplier performance.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SupplierPerformanceDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Compare suppliers’ performance","tags":["Suppliers"]}},"/api/suppliers/{supplierId}/performance":{"get":{"description":"On-time delivery, fill rate, return rate, invoice exception rate, average lead time, quotation win rate, and spend per currency — all derived from recorded documents, none typed in.","operationId":"forSupplier","parameters":[{"name":"supplierId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"from","required":false,"in":"query","description":"Start of the period, inclusive. Each metric dates its own events: due\ndates for delivery, closing for fill rate, receipt for returns,\nsubmission for invoices, issue for lead time, receipt for quotations,\npayment date for paid. Committed and invoiced spend are current totals.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"End of the period, inclusive.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierPerformanceDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"A supplier’s performance","tags":["Suppliers"]}},"/api/inventory-adjustments":{"post":{"description":"Opens a **draft** correction to one store’s stock, optionally with its lines. The reason fixes the direction — `DAMAGED` and `SCRAPPED` write stock off, `FOUND` brings it on — and quantities are always positive. A draft moves nothing; it must be submitted and then approved by someone else.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryAdjustmentDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such store, stock item or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The store or a bin is inactive, a bin is transit, an item is not stock-controlled, or you have no membership to record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Prepare an inventory adjustment","tags":["Inventory Adjustments"]},"get":{"description":"Newest first. Filterable by `status`, `reason`, `storeId` and `stockItemId`.","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","SUBMITTED","POSTED","REJECTED","CANCELLED"]}},{"name":"reason","required":false,"in":"query","schema":{"type":"string","enum":["DAMAGED","SCRAPPED","FOUND"]}},{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"stockItemId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of adjustments.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryAdjustmentDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List inventory adjustments","tags":["Inventory Adjustments"]}},"/api/inventory-adjustments/{inventoryAdjustmentId}":{"get":{"description":"The correction and its full trail — who created, submitted, approved or rejected, and cancelled it, and when. Another organization’s adjustment returns 404.","operationId":"findOne","parameters":[{"name":"inventoryAdjustmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such inventory adjustment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get an inventory adjustment","tags":["Inventory Adjustments"]},"patch":{"description":"Reason, explanation, reference — and the store, while there are no lines. Only a draft; a submitted adjustment is frozen for its decision.","operationId":"update","parameters":[{"name":"inventoryAdjustmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryAdjustmentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such inventory adjustment or store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The adjustment is not a draft, or the store has lines.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft inventory adjustment","tags":["Inventory Adjustments"]}},"/api/inventory-adjustments/{inventoryAdjustmentId}/submit":{"post":{"description":"Freezes the draft and sends it for a decision. Lines are validated now — active bins, never transit, stock-controlled items — so an approver never decides on something that cannot post. Moves no stock.","operationId":"submit","parameters":[{"name":"inventoryAdjustmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such inventory adjustment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`EMPTY_INVENTORY_ADJUSTMENT`, `ADJUSTMENT_STORE_INACTIVE`, `STORE_LOCATION_NOT_A_BIN`, `STOCK_ITEM_NOT_STOCK_CONTROLLED`, or the adjustment is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Submit an adjustment for approval","tags":["Inventory Adjustments"]}},"/api/inventory-adjustments/{inventoryAdjustmentId}/approve":{"post":{"description":"Writes one `ADJUSTMENT` movement per line — negative for a write-off, positive for found stock — and records you as the approver. **Never your own**: whoever created or submitted the adjustment cannot approve it, enforced by the database.\n\n**Negative stock is impossible.** A write-off takes stock out under the same per-position lock an issue takes, re-summed in PostgreSQL, so two write-offs (or a write-off and an issue) racing for the last bag cannot both succeed. Approving an already-posted adjustment returns it unchanged.","operationId":"approve","parameters":[{"name":"inventoryAdjustmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\n`INVENTORY_ADJUSTMENT_SELF_APPROVAL`: you created or submitted it."},"404":{"description":"No such inventory adjustment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`INSUFFICIENT_STOCK`, `ADJUSTMENT_STORE_INACTIVE`, or the adjustment is not submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Approve and post an adjustment","tags":["Inventory Adjustments"]}},"/api/inventory-adjustments/{inventoryAdjustmentId}/reject":{"post":{"description":"Refuses a submitted adjustment, with a required reason. Terminal: a corrected request is a new adjustment. Moves no stock.","operationId":"reject","parameters":[{"name":"inventoryAdjustmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentDecisionReasonDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such inventory adjustment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The adjustment is not submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Reject an adjustment","tags":["Inventory Adjustments"]}},"/api/inventory-adjustments/{inventoryAdjustmentId}/cancel":{"post":{"description":"Cancels a draft or submitted adjustment before it is decided, with a required reason. A posted adjustment cannot be cancelled — it is corrected by another adjustment.","operationId":"cancel","parameters":[{"name":"inventoryAdjustmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentDecisionReasonDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such inventory adjustment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The adjustment is already decided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Withdraw an adjustment","tags":["Inventory Adjustments"]}},"/api/inventory-adjustments/{inventoryAdjustmentId}/lines":{"get":{"description":"Each line with its positive quantity and the signed quantity posting writes.","operationId":"listLines","parameters":[{"name":"inventoryAdjustmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of lines.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryAdjustmentLineDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such inventory adjustment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List an adjustment’s lines","tags":["Inventory Adjustments"]},"post":{"description":"A stock-controlled item, the bin inside the adjustment’s store (omit for unbinned stock; never transit) and a positive quantity. Stock is checked when approved.","operationId":"createLine","parameters":[{"name":"inventoryAdjustmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryAdjustmentLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such inventory adjustment, stock item or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The adjustment is not a draft, the item is not stock-controlled, or the bin is transit or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a line to a draft adjustment","tags":["Inventory Adjustments"]}},"/api/inventory-adjustments/{inventoryAdjustmentId}/lines/{lineId}":{"patch":{"description":"Quantity, bin, notes and order. The item is the identity.","operationId":"updateLine","parameters":[{"name":"inventoryAdjustmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryAdjustmentLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such inventory adjustment, line or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The adjustment is not a draft, or the bin is unusable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a draft adjustment’s line","tags":["Inventory Adjustments"]},"delete":{"description":"Only while the adjustment is a draft.","operationId":"removeLine","parameters":[{"name":"inventoryAdjustmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such inventory adjustment or line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The adjustment is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from a draft adjustment","tags":["Inventory Adjustments"]}},"/api/inventory/sales":{"post":{"description":"Sells one item from a **central** store. A price below the unit cost, or a total including VAT over the organization’s `saleApprovalLimit`, leaves the order `PENDING_APPROVAL` with its quantity reserved; otherwise it is `RELEASED` at once — SALE movement, delivery note and invoice record.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSalesOrderDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesOrderDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such store, bin or stock item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The store is being counted, or you have no membership to record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"422":{"description":"A rule refused the sale: no client, a zero quantity or price, a project-site store, an item with no cost, or not enough stock. The message is worded for the sale panel."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Sell stock to a client","tags":["Sales Orders"]},"get":{"description":"Newest first. Filter by `status` — `PENDING_APPROVAL` is Finance’s queue — and `stockItemId`.","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["PENDING_APPROVAL","RELEASED","REJECTED","CANCELLED"]}},{"name":"stockItemId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of sales orders.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SalesOrderDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List sales orders","tags":["Sales Orders"]}},"/api/inventory/sales/{salesOrderId}":{"get":{"operationId":"findOne","parameters":[{"name":"salesOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesOrderDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such sales order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a sales order, with its delivery note and invoice numbers","tags":["Sales Orders"]}},"/api/inventory/sales/{salesOrderId}/approve":{"post":{"description":"By someone other than its creator. Re-checks stock under the lock, then writes the SALE movement, numbers the delivery note and creates the invoice record.","operationId":"approve","parameters":[{"name":"salesOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesOrderDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such sales order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The sale is not awaiting approval, or the store is being counted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"422":{"description":"The store no longer holds enough."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Approve a sale, releasing its stock","tags":["Sales Orders"]}},"/api/inventory/sales/{salesOrderId}/reject":{"post":{"description":"A reason is required. The reserved stock is released.","operationId":"reject","parameters":[{"name":"salesOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesOrderDecisionReasonDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesOrderDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such sales order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The sale is not awaiting approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Reject a sale awaiting approval","tags":["Sales Orders"]}},"/api/inventory/sales/{salesOrderId}/cancel":{"post":{"description":"A reason is required. The reserved stock is released.","operationId":"cancel","parameters":[{"name":"salesOrderId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesOrderDecisionReasonDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesOrderDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such sales order in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The sale has already been released, rejected or cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Cancel a sale before release","tags":["Sales Orders"]}},"/api/clients":{"get":{"description":"Name contains `q`, ignoring case; names starting with it first. Up to `limit` (20 by default).","operationId":"search","parameters":[{"name":"q","required":false,"in":"query","description":"Matches anywhere in the name, ignoring case.","schema":{"maxLength":200,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ClientDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Search clients","tags":["Customers"]},"post":{"description":"A name, and optionally phone, email and TIN. Names are unique per organization, ignoring case.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateClientDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A client with this name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a client","tags":["Customers"]}},"/api/sales-invoices":{"get":{"description":"Newest first. Filter by derived `status` (UNPAID, OVERDUE, PAID), search `q` (client, invoice or sales order number) and an issued-on range. `counts` give each status within the same search and range.","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["UNPAID","OVERDUE","PAID"]}},{"name":"q","required":false,"in":"query","description":"Client name, invoice number or sales order number, contains, any case.","schema":{"maxLength":100,"type":"string"}},{"name":"from","required":false,"in":"query","description":"Issued on or after this day, in the organization's time zone.","schema":{"format":"date","type":"string"}},{"name":"to","required":false,"in":"query","description":"Issued on or before this day.","schema":{"format":"date","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesInvoicePageDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List sales invoices","tags":["Sales Orders"]}},"/api/sales-invoices/{salesInvoiceId}":{"get":{"description":"With its lines, the client’s details, cost of goods and margin (internal), and the history of its paid mark.","operationId":"findOne","parameters":[{"name":"salesInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesInvoiceDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such sales invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a sales invoice","tags":["Sales Orders"]}},"/api/sales-invoices/{salesInvoiceId}/mark-paid":{"post":{"description":"Records the day the client paid (today when omitted) and who recorded it. No amounts. Already paid: returned unchanged.","operationId":"markPaid","parameters":[{"name":"salesInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkSalesInvoicePaidDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesInvoiceDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such sales invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Mark a sales invoice paid","tags":["Sales Orders"]}},"/api/sales-invoices/{salesInvoiceId}/mark-unpaid":{"post":{"description":"For a payment recorded in error. Audited.","operationId":"markUnpaid","parameters":[{"name":"salesInvoiceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesInvoiceDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such sales invoice in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Undo a sales invoice’s paid mark","tags":["Sales Orders"]}},"/api/requisition-payments":{"get":{"description":"Approved pay-directly requisition lines — fuel, labour, mobile money charges — that Finance pays without a purchase order. To pay first. `facets` gives each filter chip’s count under the other filters.","operationId":"list","parameters":[{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["TO_PAY","PAID"]}},{"name":"projectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"requisitionTypeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Requisition number, line description, payee name or account.","schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentsToMakePageDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Payments to make","tags":["Supplier Invoices"]},"post":{"description":"Pays one line, or several under one reference (a batch mobile money payment). Each line’s amount defaults to its approved amount; a different amount needs a `note`. The payee must be known. Proof is required for mobile money and bank. Sets each line’s actual amount unless one was already recorded by hand, which is kept.","operationId":"record","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"string","description":"JSON of `RecordRequisitionPaymentDto`: `{ lines: [{ requisitionLineId, amount?, note?, payeeName?, payeeAccount? }], paidOn, method, reference? }`."},"file":{"type":"string","format":"binary","description":"Proof of payment. Required for MOBILE_MONEY and BANK. JPEG, PNG, WebP or PDF."}}}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordedPaymentDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A line is not payable: not PAY, not approved, or paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Record a payment","tags":["Supplier Invoices"]}},"/api/requisition-payments/{paymentId}/void":{"post":{"description":"The line goes back to To pay and the actual amount the payment set is cleared. An actual recorded by hand before the payment is left as it is. Audited with the reason.","operationId":"void","parameters":[{"name":"paymentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoidRequisitionPaymentDto"}}}},"responses":{"204":{"description":"The payment was voided."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such payment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Void a payment","tags":["Supplier Invoices"]}},"/api/requisition-payment-batches/{batchId}/attachments":{"get":{"operationId":"proof","parameters":[{"name":"batchId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such payment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"A payment’s proof","tags":["Supplier Invoices"]}},"/api/admin/requisition-routes/preview":{"get":{"description":"Per mapped type name: the type it matches (ignoring case and extra spaces), its new route, and how many approved lines with no purchase order would move to Payments to make. Lists mapped names that matched nothing. Changes nothing.","operationId":"preview","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteSwitchPreviewDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Dry run of the agreed requisition route mapping","tags":["Master Data"]}},"/api/admin/requisition-routes/apply":{"post":{"description":"Exactly what the preview showed: sets type routes, tidies four names, creates Fuel if missing, and moves approved lines with no purchase order whose new route is PAY. Lines with an order keep STOCK. Returns a `switchBatchId` to revert with.","operationId":"apply","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteSwitchResultDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Apply the agreed requisition route mapping","tags":["Master Data"]}},"/api/admin/requisition-routes/revert/{switchBatchId}":{"post":{"description":"Puts the types and lines of one switch-over back on their previous routes, from the audit. A line Finance has already paid is skipped and listed.","operationId":"revert","parameters":[{"name":"switchBatchId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteSwitchRevertDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such switch-over, or it was already reverted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Revert a switch-over","tags":["Master Data"]}},"/api/requisition-lines/{lineId}/confirm-received":{"post":{"description":"PURCHASE lines only, once on an issued purchase order. By the requester, or anyone holding `requisition.update`. Confirming again corrects the date and note.","operationId":"confirm","parameters":[{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmReceivedDto"}}}},"responses":{"204":{"description":"Confirmed."},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such line in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The line is not a purchase line, or is not ordered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Confirm a purchase-not-stocked line arrived or was done","tags":["Requisitions"]}},"/api/stock-counts":{"post":{"description":"Opens a count of one store. With `scope` its lines are filled at once: ALL_ITEMS (every active material, items with no stock here at 0 — how opening balances get in), HELD_ONLY or CATEGORIES (`categoryIds`, subcategories included). With `start: true` counting opens too, snapshotting every line, in the same transaction: nothing half-made is left if any step fails. Filling or starting also needs `stock_count.update`.\n\nWithout either, a **draft** to add positions to by hand, then start.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStockCountDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The store is inactive or already being counted, the scope covers no items (`EMPTY_STOCK_COUNT`), or you have no membership to record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Open a stock count","tags":["Stock Counts"]},"get":{"description":"Newest first. Filterable by `status` and `storeId`.","operationId":"list","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["DRAFT","COUNTING","SUBMITTED","AWAITING_FINANCE","POSTED","CANCELLED"]}},{"name":"group","required":false,"in":"query","description":"OPEN: not yet posted or cancelled. COUNTING: draft or counting. AWAITING: either approval. APPROVED: posted. CLOSED: cancelled.","schema":{"type":"string","enum":["OPEN","COUNTING","AWAITING","APPROVED","CLOSED"]}},{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of stock counts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockCountDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List stock counts","tags":["Stock Counts"]}},"/api/stock-counts/status-counts":{"get":{"description":"For the tab’s badge and chips, optionally for one store — and how many are waiting on an approval you may give now.","operationId":"statusCounts","parameters":[{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountStatusCountsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"How many counts each status group holds","tags":["Stock Counts"]}},"/api/stock-counts/scope-preview":{"get":{"description":"For the open-count form: positions every catalogue item would give at `storeId`, positions holding stock now, and per top-level category.","operationId":"scopePreview","parameters":[{"name":"storeId","required":true,"in":"query","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountScopePreviewDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"How many items each scope would count","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/history":{"get":{"description":"Every step, newest first — opened, items added (mid-count too), started, date changes, submitted, each return for recount, approvals, cancellation or rejection — with who and any reason given.","operationId":"history","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of history.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockCountEventDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"A count’s history","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/candidates":{"get":{"description":"Active stock-controlled materials with no line on the count, matching `q` on code or name, a page at a time — for \"found something not on the list?\".","operationId":"candidates","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"q","required":false,"in":"query","description":"Item code or name.","schema":{"maxLength":100,"type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of items.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockCountCandidateDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Items a count could still add","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}":{"get":{"description":"The count, its progress (`countedLineCount` of `lineCount`) and its trail. No quantities. Another organization’s count returns 404.","operationId":"findOne","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get a stock count","tags":["Stock Counts"]},"patch":{"description":"While a draft: description, notes, count date, blind or visible — and the store, while the count has no positions. While counting: the count date alone.","operationId":"update","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStockCountDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count or store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The count is not a draft, or it has positions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Update a stock count","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/start":{"post":{"description":"Freezes the positions and opens counting. Refused while another count of the same store is being counted or reviewed (`STOCK_COUNT_ALREADY_OPEN`).","operationId":"start","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`STOCK_COUNT_ALREADY_OPEN`, `EMPTY_STOCK_COUNT`, `STOCK_COUNT_STORE_INACTIVE`, or the count is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Start counting","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/submit":{"post":{"description":"Closes the round. Every position must have a count for its current round — zero is a count.","operationId":"submit","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`STOCK_COUNT_INCOMPLETE`, or the count is not counting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Submit a count for review","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/variances":{"get":{"description":"The reviewer’s read — **not available to counters**. `lineIds` narrows it to the lines on screen. Per position: the effective count, the system quantity snapshotted when it was entered (or when counting started, until it is), the variance (`counted − system`, computed by PostgreSQL — exactly what posting writes), the balance now, whether it is stale, and every round.","operationId":"variances","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineIds","required":false,"in":"query","description":"Only these lines — the page on screen. Omit for every line.","schema":{"maxItems":100,"type":"array","items":{"type":"string","format":"uuid"}}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StockCountVarianceDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Review a count’s variances","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/recount":{"post":{"description":"Opens a new round for the named positions, with a required comment, and returns the count to COUNTING — from either approval level, by a reviewer who could approve that level. The approval chain restarts: a level-1 approval does not carry over. Earlier rounds are kept; the counter does not see them.","operationId":"recount","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecountStockCountDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.\n\nA position is not on this count."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\n`STOCK_COUNT_SELF_APPROVAL`: you cannot act at this level — the message says why."},"404":{"description":"No such stock count in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The count is not awaiting an approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Return a count for recount","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/approve":{"post":{"description":"**Level 1** (SUBMITTED, `stock_count.approve`): every variance needs a reason (`STOCK_COUNT_REASON_REQUIRED`). If the gross variance value — Σ |variance × unit cost| — is over the organization’s finance limit, or any variance cannot be valued, the count moves to AWAITING_FINANCE; otherwise it posts. **Level 2** (AWAITING_FINANCE, `stock_count.approve_finance`): posts. Nobody who planned, started, submitted or counted the count may approve it, and level 2 is never the level-1 approver.\n\nPosting writes one `ADJUSTMENT` per position whose variance is not zero — the difference, applied to the balance as it now stands, so movements since the count stay as they happened. **Never a count you counted.**\n\nRefused, writing nothing, if a position has been adjusted since it was counted (`STOCK_COUNT_STALE` — recount it), or if a shortage would take a position below zero (`INSUFFICIENT_STOCK`), checked under the same per-position lock an issue takes. Approving an already-posted count returns it unchanged.","operationId":"approve","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\n`STOCK_COUNT_SELF_APPROVAL`: you cannot approve this level — the message says why."},"404":{"description":"No such stock count in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`STOCK_COUNT_REASON_REQUIRED`, `STOCK_COUNT_STALE`, `INSUFFICIENT_STOCK`, `STOCK_COUNT_STORE_INACTIVE`, or the count is not awaiting an approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Approve a count at the level it waits on","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/cancel":{"post":{"description":"Ends a count before it is posted, with a required reason, and frees the store for another count. Moves no stock.\n\n**Open** (DRAFT or COUNTING) with nothing counted yet: needs `stock_count.cancel`. Once any figure is entered it is refused (`409 STOCK_COUNT_HAS_COUNTS`): submit it, and an approver returns it for recount or rejects it.\n\n**Awaiting approval** (SUBMITTED or AWAITING_FINANCE): a rejection, by an approver for the level it waits on — nobody who took part in the count (`403 STOCK_COUNT_SELF_APPROVAL`).","operationId":"cancel","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelStockCountDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\n`STOCK_COUNT_CANCEL_FORBIDDEN` for an open count without `stock_count.cancel`; `STOCK_COUNT_SELF_APPROVAL` for a rejection the caller may not give."},"404":{"description":"No such stock count in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The count is posted, or figures have been entered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Cancel or reject a stock count","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/lines":{"get":{"description":"What to count, and what has been counted in the current round, in count order. `q` searches item code and name; `filter` narrows to `uncounted`, `counted` or `variance` lines (`variance` on a blind count is the reviewer’s only). On a **blind** count: no system quantity, no variance, no reason, no earlier round — the keys are absent. On a **visible** count each line also carries `systemQuantity`, `variance`, `varianceReason` and `varianceNote`. A counter who also holds `stock_movement.view` can still read balances from `/stock-balances`; a truly blind counter is given `stock_count.count` without it.","operationId":"listLines","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"q","required":false,"in":"query","description":"Item code or name.","schema":{"maxLength":100,"type":"string"}},{"name":"filter","required":false,"in":"query","description":"`variance`: counted lines that differ from the system quantity — refused on a blind count to anyone but a reviewer.","schema":{"type":"string","enum":["uncounted","counted","variance"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of positions.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockCountLineDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"List a count’s positions","tags":["Stock Counts"]},"post":{"description":"A stock-controlled item in an active bin of the count’s store (omit the bin for unbinned stock; never transit). Each position once per count. A position with no recorded stock may be counted too — anything found there is a positive variance.\n\nAllowed while **counting** too, for something found that is not on the list: the line takes its system-quantity snapshot at once, and the addition is written to the count’s history.","operationId":"createLine","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStockCountLineDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count, stock item or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`DUPLICATE_STOCK_COUNT_LINE`, the count is not a draft, the item is not stock-controlled, or the bin is transit or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add a position to a count","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/lines/populate":{"post":{"description":"Adds every position the `scope` covers that the count lacks: HELD_ONLY (default) the positions holding stock — optionally within one bin, for a cycle count; ALL_ITEMS every active material, items never held here at 0; CATEGORIES those in `categoryIds`. Returns how many were added; never their quantities.\n\nAllowed while counting, e.g. to give an empty count its catalogue: the new lines are snapshotted at once and the addition is written to the history.","operationId":"populate","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PopulateStockCountDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PopulatedStockCountDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count or bin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The count is past counting, or the bin is unusable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Fill a count from a scope","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/lines/{lineId}":{"delete":{"description":"Only while the count is a draft.","operationId":"removeLine","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count or position.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The count is not a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove a position from a draft count","tags":["Stock Counts"]},"patch":{"description":"The counter’s note on the line’s photos. Blank or null clears it. Only while the count is COUNTING (`409 STOCK_COUNT_PHOTOS_LOCKED` otherwise).","operationId":"updateLine","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStockCountLineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count or line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Photos can't be changed after the count is submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Set a line’s evidence note","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/lines/{lineId}/count":{"post":{"description":"What is physically at the position, as a non-negative decimal string. The system quantity is snapshotted beside it, under the position lock — and on a blind count **not returned**. May be re-keyed while the round is open. On a visible count, send `varianceReason` with a count that differs; a blind count refuses one (`STOCK_COUNT_BLIND_REASON`).","operationId":"record","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordStockCountDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountLineDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count or position.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"The count is not counting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Record a count","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/lines/{lineId}/reason":{"post":{"description":"For a blind count, whose counters cannot see variances: the level-1 reviewer explains each one while the count is SUBMITTED, before approving. Only a reviewer who could approve it.","operationId":"setReason","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetStockCountVarianceReasonDto"}}}},"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.\n\n`STOCK_COUNT_SELF_APPROVAL`: you cannot review this count — the message says why."},"404":{"description":"No such stock count in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"`STOCK_COUNT_NO_VARIANCE`, or the count is not awaiting the stores approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Give a variance its reason","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/lines/{lineId}/photos":{"get":{"description":"Oldest first. Anyone who can view or review the count may see them; they are never the item’s photo.","operationId":"listPhotos","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StockCountLinePhotoDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count or line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"A line’s evidence photos","tags":["Stock Counts"]},"post":{"description":"One or more images in `files` parts: JPEG, PNG, WebP or HEIC/HEIF, checked by content, up to 5 MB each (`413 IMAGE_TOO_LARGE`). A line holds at most 6; a batch that would pass that is refused whole (`422 STOCK_COUNT_PHOTO_LIMIT`).\n\nProcessed like item photos (WebP within 1600 px plus a 160 px thumbnail, HEIC converted, EXIF orientation applied, all metadata including GPS removed) but stored apart from them, under `stock_counts/{count}/{line}/`. Only while the count is COUNTING (`409 STOCK_COUNT_PHOTOS_LOCKED` otherwise, for everyone — approvers included), and then only with `stock_count.count` (`403`). Each photo is recorded in the count’s history.","operationId":"addPhotos","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"array","items":{"type":"string","format":"binary"}}}}}}},"responses":{"201":{"description":"Every photo now on the line.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StockCountLinePhotoDto"}}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count or line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Photos can't be changed after the count is submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"413":{"description":"Image is larger than 5 MB."},"422":{"description":"Up to 6 photos per line."},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add evidence photos to a line","tags":["Stock Counts"]}},"/api/stock-counts/{stockCountId}/lines/{lineId}/photos/{photoId}":{"delete":{"description":"Only while the count is COUNTING (`409 STOCK_COUNT_PHOTOS_LOCKED` otherwise). Recorded in the count’s history.","operationId":"removePhoto","parameters":[{"name":"stockCountId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"lineId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"photoId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":""},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock count, line or photo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Photos can't be changed after the count is submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Remove an evidence photo","tags":["Stock Counts"]}},"/api/dashboard/overview":{"get":{"description":"Headline figures, portfolio, requisition pipeline, alerts, project performance and monthly spend for the projects matching `branchId`, in one request. Metric definitions are in `docs/dashboard-metrics.md`.\n\nMoney is a decimal string in `currency` — the one most live projects use — and is never converted; projects in other currencies are counted in `otherCurrencies` and left out of money totals.\n\nEach section is `null`, or each figure withheld, unless you hold the view key of the register behind it (`project.view`, `budget.view`, `purchase_order.view`, `requisition.view`/`view_own`, `approval.view`); `access` says which applied.","operationId":"overview","parameters":[{"name":"period","required":false,"in":"query","description":"Narrows flows — requisitions raised and spend — to a window ending today.\nPoint-in-time figures such as contract value and budget always describe\ntoday. Defaults to `all_time`.","schema":{"default":"all_time","type":"string","enum":["all_time","last_30_days","this_quarter","year_to_date"]}},{"name":"branchId","required":false,"in":"query","description":"One branch's projects, `unassigned` for projects with no branch, or\nomitted for the whole organization.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardOverviewDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Organization overview","tags":["Dashboard"]}},"/api/dashboard/settings":{"get":{"description":"Readable by anyone who can see the overview, since its alerts are judged by these. The defaults until changed.","operationId":"getSettings","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardSettingsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Get the overview thresholds","tags":["Dashboard"]},"patch":{"description":"Send only the thresholds that change. Applies to every overview read from now on.","operationId":"updateSettings","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDashboardSettingsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardSettingsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Change the overview thresholds","tags":["Dashboard"]}},"/api/inventory/overview":{"get":{"description":"Headline figures, days of cover, value by category, weekly issues, alerts and latest activity, in one request, for the stores and category in scope (every section follows the filters). Value is quantity × weighted-average cost, a decimal string in `currency`; warehouse means a central store. Status and cover are judged on warehouse stock whatever the scope. Open orders, suppliers and lead times also need `purchase_order.view`, and requisitions `requisition.view`; without them those figures are withheld and the alerts built on them are not raised. `access` says which applied.","operationId":"overview","parameters":[{"name":"storeId","required":false,"in":"query","description":"One store. Wins over `storeKind`.","schema":{"format":"uuid","type":"string"}},{"name":"storeKind","required":false,"in":"query","description":"Every warehouse (central store) or every project site store.","schema":{"type":"string","enum":["CENTRAL","SITE"]}},{"name":"categoryId","required":false,"in":"query","description":"A category — its subcategories included — or one subcategory.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryOverviewDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Inventory overview","tags":["Inventory"]}},"/api/inventory/stock":{"get":{"description":"One row per material in scope, with its status, searched (`q`), narrowed by `chip` and sorted (`sortBy`, `sortDirection`) in PostgreSQL. `meta.total` respects every filter; the summary figures are `GET /inventory/materials`. Every order ends on the item id, so rows that tie never repeat or go missing between pages. Open orders, suppliers and lead times also need `purchase_order.view`, and requisitions `requisition.view`; without them those figures are withheld and the alerts built on them are not raised. `access` says which applied.","operationId":"stock","parameters":[{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"storeKind","required":false,"in":"query","schema":{"type":"string","enum":["CENTRAL","SITE"]}},{"name":"categoryId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"q","required":false,"in":"query","description":"Item code or name.","schema":{"maxLength":100,"type":"string"}},{"name":"chip","required":false,"in":"query","description":"BELOW: low, or out with a reorder level set. OUT: out of stock. NOT_STOCKED: never received.","schema":{"default":"ALL","type":"string","enum":["ALL","BELOW","OUT","NOT_STOCKED"]}},{"name":"sortBy","required":false,"in":"query","description":"status, descending (the default), puts out of stock first, then by value. Every order ends on the item id, so ties never repeat or go missing between pages.","schema":{"default":"status","example":"createdAt","type":"string","enum":["status","name","code","onHand","value","reorderLevel"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of the stock table.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MaterialRowDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"The stock table, a page at a time","tags":["Inventory"]}},"/api/inventory/movements":{"get":{"description":"Receipts, issues, transfers, returns and adjustments in scope, worded \"from → to\", filterable by item, type and date. Read by cursor: pass `meta.nextCursor` back as `cursor`. Movements posted while you read never repeat or push another off a page. Open orders, suppliers and lead times also need `purchase_order.view`, and requisitions `requisition.view`; without them those figures are withheld and the alerts built on them are not raised. `access` says which applied.","operationId":"movements","parameters":[{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"storeKind","required":false,"in":"query","schema":{"type":"string","enum":["CENTRAL","SITE"]}},{"name":"categoryId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"stockItemId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"movementType","required":false,"in":"query","schema":{"type":"string","enum":["RECEIPT","ISSUE","TRANSFER","ADJUSTMENT","RETURN","SUPPLIER_RETURN","REVERSAL","SALE"]}},{"name":"movedFrom","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"movedTo","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"cursor","required":false,"in":"query","description":"From the previous page’s `meta.nextCursor`. Omit for the newest movements.","schema":{"maxLength":200,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryMovementsPageDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Movements, newest first, by cursor","tags":["Inventory"]}},"/api/inventory/materials":{"get":{"description":"The Materials tab’s summary for the stores and category in scope: KPIs, how many rows each status chip holds, reorder alerts, value by store and recent movements. The rows themselves are `GET /inventory/stock`. Status always compares **warehouse** stock with the reorder level, whatever the scope: site stock is already charged to its project. Open orders, suppliers and lead times also need `purchase_order.view`, and requisitions `requisition.view`; without them those figures are withheld and the alerts built on them are not raised. `access` says which applied.","operationId":"materials","parameters":[{"name":"storeId","required":false,"in":"query","description":"One store. Wins over `storeKind`.","schema":{"format":"uuid","type":"string"}},{"name":"storeKind","required":false,"in":"query","description":"Every warehouse (central store) or every project site store.","schema":{"type":"string","enum":["CENTRAL","SITE"]}},{"name":"categoryId","required":false,"in":"query","description":"A category — its subcategories included — or one subcategory.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryMaterialsDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Materials, scoped","tags":["Inventory"]}},"/api/inventory/materials/{stockItemId}":{"get":{"description":"Where it is held, its last four movements, and the records linked to it: last supplier, open order, last requisition, value at sites. Open orders, suppliers and lead times also need `purchase_order.view`, and requisitions `requisition.view`; without them those figures are withheld and the alerts built on them are not raised. `access` says which applied.","operationId":"materialDetail","parameters":[{"name":"stockItemId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryMaterialDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such stock item in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"One material in detail","tags":["Inventory"]}},"/api/equipment":{"get":{"description":"Paged, within the Location (`storeId`, `storeKind`, `projectId`) and Category filters. `group` narrows to in store, on site or unavailable (under repair or out of service). Disposed assets are left out unless `includeDisposed`.","operationId":"list","parameters":[{"name":"storeId","required":false,"in":"query","description":"A warehouse, or a site store — meaning its project.","schema":{"format":"uuid","type":"string"}},{"name":"storeKind","required":false,"in":"query","schema":{"type":"string","enum":["CENTRAL","SITE"]}},{"name":"projectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"categoryId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"q","required":false,"in":"query","description":"Tag, name or serial number.","schema":{"maxLength":100,"type":"string"}},{"name":"group","required":false,"in":"query","description":"UNAVAILABLE: under repair or out of service. Disposed assets show only with `includeDisposed`.","schema":{"type":"string","enum":["ALL","IN_STORE","ON_SITE","UNDER_REPAIR","OUT_OF_SERVICE","UNAVAILABLE"]}},{"name":"includeDisposed","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"default":"tag","example":"createdAt","type":"string","enum":["tag","name","status","nextService","dayRate"]}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of equipment.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EquipmentDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"The equipment register","tags":["Inventory"]},"post":{"description":"Into a warehouse (never a site store). Without `tag`, the next `EQ-####` is used; a tag already in use is refused with `409 DUPLICATE_EQUIPMENT_TAG`.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEquipmentDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such category, store or supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Duplicate tag, or the store is a site store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Add equipment","tags":["Inventory"]}},"/api/equipment/summary":{"get":{"description":"Counts by status, service due within the organization’s `serviceDueDays`, charged to projects to date, asset value, the alerts and value by location — within the same filters as the register. Charges are a report: nothing is posted to project budgets.","operationId":"summary","parameters":[{"name":"storeId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"storeKind","required":false,"in":"query","schema":{"type":"string","enum":["CENTRAL","SITE"]}},{"name":"categoryId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentSummaryDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"The Plant & equipment figures","tags":["Inventory"]}},"/api/equipment/{equipmentId}":{"get":{"operationId":"findOne","parameters":[{"name":"equipmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such equipment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"One asset, with its charge periods","tags":["Inventory"]},"patch":{"description":"Name, category, make and model, values and service plan. Where it is and its status change only through the moves.","operationId":"update","parameters":[{"name":"equipmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEquipmentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such equipment, category or supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Edit an asset’s details","tags":["Inventory"]}},"/api/equipment/{equipmentId}/history":{"get":{"operationId":"history","parameters":[{"name":"equipmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"page","required":true,"in":"query","description":"1-based page number.","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Maximum items to return. Capped to protect the database from unbounded\nscans over large procurement and inventory tables.","schema":{"minimum":1,"maximum":100,"default":25,"example":25,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Property to sort by. Valid values depend on the endpoint.","schema":{"example":"createdAt","type":"string"}},{"name":"sortDirection","required":true,"in":"query","description":"Sort direction.","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of moves.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedDto"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EquipmentMovementDto"}}}}]}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such equipment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"An asset’s moves, newest first","tags":["Inventory"]}},"/api/equipment/{equipmentId}/issue":{"post":{"description":"From a warehouse to a project’s site; its day rate is charged from that date. Refused with `409 STORE_COUNT_IN_PROGRESS` while the warehouse is being counted.","operationId":"issue","parameters":[{"name":"equipmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueEquipmentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such equipment, project or requisition in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Not in store, or its store is being counted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Issue to a project","tags":["Inventory"]}},"/api/equipment/{equipmentId}/transfer":{"post":{"description":"From a warehouse to another (`toStoreId`), or from one project’s site straight to another’s (`toProjectId`) — closing the first project’s charge and opening the second’s.","operationId":"transfer","parameters":[{"name":"equipmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferEquipmentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such equipment, store or project in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Its status doesn’t allow a transfer, or its store is being counted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Transfer","tags":["Inventory"]}},"/api/equipment/{equipmentId}/return":{"post":{"description":"Back to a warehouse; its project charge stops on that date.","operationId":"returnToStore","parameters":[{"name":"equipmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnEquipmentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such equipment or store in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Not on site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Return from site","tags":["Inventory"]}},"/api/equipment/{equipmentId}/service-out":{"post":{"description":"To `vendorId`, or its usual service vendor (`400 EQUIPMENT_VENDOR_REQUIRED` when it has none). From site, its charge stops while it is away.","operationId":"serviceOut","parameters":[{"name":"equipmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceOutDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such equipment or supplier in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Its status doesn’t allow sending it for service.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Send for service","tags":["Inventory"]}},"/api/equipment/{equipmentId}/service-in":{"post":{"description":"To `toStoreId` (default: the warehouse it left), or with `backToSite` straight back to the project it left. The next service moves on by its service interval.","operationId":"serviceIn","parameters":[{"name":"equipmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such equipment or store in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Not under repair.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Back from service","tags":["Inventory"]}},"/api/equipment/{equipmentId}/status":{"post":{"description":"`OUT_OF_SERVICE` or `IN_STORE` (mark an out-of-service asset available), each with a reason. Back from a vendor beyond repair, `toStoreId` says where it is kept.","operationId":"setStatus","parameters":[{"name":"equipmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentStatusDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such equipment or store in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Its status doesn’t allow that change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Out of service, or available again","tags":["Inventory"]}},"/api/equipment/{equipmentId}/dispose":{"post":{"description":"Off the books for good, with a reason — from store, from a vendor, or out of service; never from site. Nothing can be done with it after.","operationId":"dispose","parameters":[{"name":"equipmentId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisposeEquipmentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentDetailDto"}}}},"400":{"description":"The request failed validation. `message` lists one entry per failed constraint. Unknown properties are rejected rather than ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Authenticated, but the caller lacks permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"No such equipment in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Its status doesn’t allow disposal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Unexpected server error. Internal detail is written to the server log against the returned `requestId`, never to the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearerAuth":[]}],"summary":"Dispose of an asset","tags":["Inventory"]}}},"info":{"title":"Tetrabuild ERP API","description":"REST API for the Tetrabuild ERP, the operational system for a construction and\nquantity-surveying business.\n\nAs modules are delivered, this API will cover projects and work breakdown,\nprocurement, inventory, costing, CRM and accounting integrations. **Only the\nendpoints documented below are implemented today** — this document describes\nthe API as it exists, not a roadmap.\n\n### Conventions\n\n- All routes are served under the `/api` prefix.\n- Request and response bodies are `application/json`.\n- Unknown request properties are **rejected**, not ignored, so a misspelled\n  field fails loudly rather than being silently dropped.\n- Monetary values are decimal strings, never floating-point numbers, to avoid\n  rounding drift in valuations and payments.\n- Timestamps are ISO 8601 with an explicit offset (UTC).\n\n### Errors\n\nEvery failure returns the same envelope, so a client needs one error path\nrather than one per endpoint:\n\n```json\n{\n  \"success\": false,\n  \"statusCode\": 400,\n  \"message\": \"Validation failed\",\n  \"error\": \"Bad Request\",\n  \"path\": \"/api/example\",\n  \"timestamp\": \"2026-09-02T10:00:00.000Z\",\n  \"requestId\": \"3f1c2b7e-9a44-4c8f-91f2-0f5b2a7d6c10\"\n}\n```\n\nStack traces, SQL and driver messages are never returned to clients; they are\nwritten to the server log against the same `requestId`.\n\n### Request correlation\n\nEvery request carries an `x-request-id` header. Send your own to trace a call\nacross systems, or one is generated. It is returned on the response and\nincluded in every error body — **quote it when reporting a problem.**\n\n### Authentication\n\nEndpoints are protected by a bearer (JWT) access token. **Authentication is\nenforced**: every route requires a valid token except the ones marked public\nbelow.\n\nSign in with `POST /api/auth/login`, then send the `accessToken` as\n`Authorization: Bearer <token>`. In this page, use **Authorize** — the token\npersists across reloads.\n\nAccess tokens are short-lived (15 minutes). Exchange the `refreshToken` at\n`POST /api/auth/refresh` for a new pair; refresh tokens are single-use and\nrotated, and replaying a consumed one revokes the whole session family.\n\n**Public endpoints** (no token): `/api/health`, `/api/auth/login`,\n`/api/auth/refresh`, `/api/auth/logout`. Everything else returns `401`\nwithout a valid token, and `403` when the token is valid but the caller lacks\nthe permission the endpoint declares.\n\n### Organization scope\n\nA session is scoped to one organization, fixed at sign-in. Requests for another\norganization's data return `404`, not `403` — a 403 would confirm that the\nrecord exists, disclosing the platform's client list.\n\nPermissions are resolved per request from the database, so a role change or a\nsuspension takes effect on the very next call rather than when the token\nexpires.","version":"0.1.0","contact":{}},"tags":[{"name":"Health","description":"Service and dependency health probes used by container orchestration."},{"name":"Authentication","description":"Sign-in, token refresh and sign-out. Sessions are scoped to one organization."},{"name":"Organizations","description":"Organizations and their branches — the top of the tenancy hierarchy."},{"name":"Users","description":"Users and their membership of an organization, including role assignment."},{"name":"Roles","description":"Organization-scoped roles and the global catalogue of permissions they grant."},{"name":"Staff","description":"The staff directory — who works here, in which department, under what job title. A directory only: assignments grant no access."},{"name":"Master Data","description":"Organization master data — departments and cost centres that downstream modules reference."},{"name":"Projects","description":"Construction projects — the anchor downstream ERP records attach to."},{"name":"Project Members","description":"The people assigned to a project, and their project role."},{"name":"BOQ","description":"Bills of quantities — the priced scope of work a project is measured and valued against."},{"name":"Budgets","description":"Project budgets and their lines — baseline, variations, actuals and forecast, reconciled per line."},{"name":"Requisitions","description":"Requests to buy — raised against a project and its budget, and routed for approval before procurement can act on them."},{"name":"Approvals","description":"The approval workflow for requisitions — pending approvals, and the approve/reject actions taken on them."},{"name":"Approval Policies","description":"The rules that decide who must approve a requisition, and in what order."},{"name":"Suppliers","description":"The parties the organization buys from. Organization-wide master data; retired by deactivation, never deleted."},{"name":"Supplier Invoices","description":"What suppliers say the firm owes, matched three ways against the order and the goods received. An approved invoice is an amount owed and feeds budget actuals."},{"name":"Supplier Payments","description":"Payments recorded against approved supplier invoices, supplier statements and payables aging. Recorded, not executed — the system moves no money."},{"name":"Sourcing","description":"Requests for quotation and the quotations suppliers return. An award raises draft purchase orders at the quoted prices; nothing is sent to suppliers."},{"name":"Subcontracts","description":"Packages of the works let against a schedule of rates: variations change the schedule once approved; certified valuations raise approved supplier invoices, net of retention."},{"name":"Procurement","description":"Purchase orders — the point at which an approved request becomes a commitment to a supplier. A commitment is not yet a cost."},{"name":"Goods Receipts","description":"Goods receipts — the record that what was ordered actually arrived. A posted receipt is immutable; correcting one means reversing it and recording another. Receiving is not yet stock: where the goods now sit is Inventory."},{"name":"Inventory","description":"Stock items, stores and the stock ledger. A balance is not a stored number: it is the sum of every movement affecting a store and an item, so each figure is explainable by the documents behind it. Movements are created by posting documents — goods receipts bring stock in, material issues take it out, stock transfers move it between locations, material and supplier returns bring it back or send it away, and approved adjustments and stock counts correct it — and by nothing else: there is deliberately no endpoint that sets a quantity."},{"name":"Material Issues","description":"Material issues — stock released from a store or bin to a project against an approved requisition. Posting writes negative ledger movements under a per-position lock, so stock can never go negative; a posted issue is immutable and is corrected only by reversing it."},{"name":"Stock Transfers","description":"Stock transfers — stock moved between two locations on behalf of a project, confirmed twice. Dispatch moves it out of the source bin into the source store’s transit location; receipt moves it out of transit into the destination bin. Both write ledger movements under the same per-position lock as an issue, so stock is never negative, never lost and never counted twice. A dispatched transfer is immutable."},{"name":"Material Returns","description":"Material returns — unused material physically back from site into a store, against the posted material issue that sent it. Capped at what each issue line released, checked under a lock; posting writes positive RETURN movements. Not a reversal: an issue reversal says the goods never left, a return says they came back."},{"name":"Supplier Returns","description":"Supplier returns — goods sent back to the supplier, against the posted goods receipt that brought them in. Capped at what each receipt line received; posting writes negative SUPPLIER_RETURN movements under the per-position lock, so stock is never negative. The order’s received quantity is unchanged — replacement and credit are a later stage."},{"name":"Inventory Adjustments","description":"Inventory adjustments — approved corrections to what a store holds: damaged or scrapped stock written off, or found stock brought on. The direction comes from the reason, never the client; every adjustment is submitted and then approved by someone other than its author before it writes an ADJUSTMENT movement."},{"name":"Stock Counts","description":"Stock counts — blind physical counts of a store. Counters never see the system quantity; it is snapshotted as each count is entered. Reviewers see the variance, may send lines back for recount, and posting writes one ADJUSTMENT per variance — the difference, applied to the balance as it now stands."},{"name":"Sales Orders","description":"Sales to clients — stock sold from a central store, never a project site. A sale below cost or over the organization’s sale approval limit waits for Finance with its quantity reserved; otherwise, and on approval, it is released at once: a negative SALE movement at the unit cost at sale, a delivery note and an invoice record carrying revenue, VAT and cost of goods. There is no general ledger yet."},{"name":"Customers","description":"Clients stock is sold to — the smallest record Finance can invoice: a name unique per organization, phone, email and TIN. Search for a picker, and quick-add."},{"name":"Audit","description":"A project's audit trail — business-meaningful events recorded as they happen: BOQ ratification, requisition submission and decisions, purchase order actions, goods receipt posting, and project membership changes. Read-only and immutable; there is no endpoint that writes a row directly."},{"name":"Dashboard","description":"The organization Overview — headline figures, alerts and project performance across the portfolio, and the thresholds they are judged by."}],"servers":[{"url":"/","description":"This server"}],"components":{"securitySchemes":{"bearerAuth":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"JWT access token from POST /api/auth/login. Expires after 15 minutes."}},"schemas":{"ErrorResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":false},"statusCode":{"type":"number","example":400},"message":{"description":"Human-readable description. A single string for most failures, or one entry per failed constraint when request validation fails.","oneOf":[{"type":"string","example":"Validation failed"},{"type":"array","items":{"type":"string"}}],"example":"Validation failed"},"error":{"type":"string","example":"Bad Request"},"code":{"type":"string","description":"Stable machine-readable code, present for domain errors.","example":"INSUFFICIENT_STOCK"},"path":{"type":"string","example":"/api/health"},"timestamp":{"type":"string","example":"2026-09-02T10:00:00.000Z"},"requestId":{"type":"string","description":"Correlation id; quote this when reporting a problem.","example":"3f1c2b7e-9a44-4c8f-91f2-0f5b2a7d6c10"}},"required":["success","statusCode","message","error","path","timestamp","requestId"]},"ValidationErrorResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":false},"statusCode":{"type":"number","example":400,"description":"Always 400 for a validation failure."},"message":{"description":"One human-readable entry per failed validation constraint. Field names match the request body.","example":["projectId must be a UUID","quantity must not be less than 1","property unitPrice should not exist"],"type":"array","items":{"oneOf":[{"type":"string","example":"Validation failed"},{"type":"array","items":{"type":"string"}}]}},"error":{"type":"string","example":"Bad Request"},"code":{"type":"string","description":"Stable machine-readable code, present for domain errors.","example":"INSUFFICIENT_STOCK"},"path":{"type":"string","example":"/api/health"},"timestamp":{"type":"string","example":"2026-09-02T10:00:00.000Z"},"requestId":{"type":"string","description":"Correlation id; quote this when reporting a problem.","example":"3f1c2b7e-9a44-4c8f-91f2-0f5b2a7d6c10"}},"required":["success","statusCode","message","error","path","timestamp","requestId"]},"LoginDto":{"type":"object","properties":{"email":{"type":"string","description":"Email address the account was created with. Case-insensitive.","example":"site.manager@tetrabuild.example","format":"email"},"password":{"type":"string","description":"Account password.","maxLength":128},"organizationId":{"type":"string","description":"Organization to sign in to. Required only when the account belongs to more\nthan one; a `400` lists the options.","format":"uuid"}},"required":["email","password"]},"AuthTokensDto":{"type":"object","properties":{"accessToken":{"type":"string","description":"Bearer token for the Authorization header."},"refreshToken":{"type":"string","description":"Opaque refresh token. Rotated on every use — store the new value and discard the old one."},"expiresIn":{"type":"string","description":"Access-token lifetime.","example":"15m"},"organizationId":{"type":"string","description":"Organization this session is scoped to."}},"required":["accessToken","refreshToken","expiresIn","organizationId"]},"RefreshTokenDto":{"type":"object","properties":{"refreshToken":{"type":"string","description":"The refresh token issued by login or a previous refresh."}},"required":["refreshToken"]},"SwitchOrganizationDto":{"type":"object","properties":{"organizationId":{"type":"string","description":"Organization the new session should be scoped to.","format":"uuid"}},"required":["organizationId"]},"ForgotPasswordDto":{"type":"object","properties":{"email":{"type":"string","description":"Address to send a temporary password to. Case-insensitive. Nothing is disclosed about whether it belongs to an account.","example":"site.manager@tetrabuild.example","format":"email"}},"required":["email"]},"ChangePasswordDto":{"type":"object","properties":{"currentPassword":{"type":"string","maxLength":128,"description":"The password currently in force — including a temporary one received by email."},"newPassword":{"type":"string","description":"Replacement password. Must differ from the current one — reusing an emailed temporary password would leave the account secured by a credential that travelled in plain text.","minLength":12,"maxLength":128}},"required":["currentPassword","newPassword"]},"CurrentUserDto":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string","example":"Walter"},"lastName":{"type":"string","example":"Ruganzu"},"fullName":{"type":"string","example":"Walter Ruganzu","description":"Display name, derived from the parts."},"organizationId":{"type":"string","description":"Organization the current session is scoped to."},"organizationTimezone":{"type":"string","description":"IANA timezone of that organization. Show every instant in it, so a reader abroad sees the same times as the site; calendar dates (`YYYY-MM-DD`) are not converted. Readable without `organization.view`.","example":"Africa/Kampala"},"permissions":{"description":"Permission keys held in this organization.","example":["organization.view","user.view"],"type":"array","items":{"type":"string"}},"roles":{"description":"Roles held in this organization.","example":["Administrator"],"type":"array","items":{"type":"string"}},"isPlatformAdmin":{"type":"boolean","description":"Whether the account may create organizations."},"mustChangePassword":{"type":"boolean","description":"Whether the account must set a new password before it can do anything else. True after a temporary password has been emailed. While it is true every endpoint except this one and `/auth/change-password` returns `403 PASSWORD_CHANGE_REQUIRED`, so a client seeing it should send the user straight to a change-password screen.","example":false},"profilePhotoUrl":{"type":"string","nullable":true,"description":"The signed-in user’s profile photo, if one has been set. Not a separate GET endpoint — joined in here the same way a requisition’s requester name is joined in for reads."},"organizationMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"The caller’s membership in the session organization — the id every recorded-by, approved-by and certified-by field names. A client compares it to hide actions the four-eyes rules would refuse (approving an invoice you recorded, certifying a valuation you prepared). Null for a platform administrator acting in an organization they are not a member of."}},"required":["id","email","firstName","lastName","fullName","organizationId","organizationTimezone","permissions","roles","mustChangePassword"]},"AttachmentDto":{"type":"object","properties":{"id":{"type":"string"},"ownerType":{"enum":["USER","STAFF_ASSIGNMENT","REQUISITION","REQUISITION_LINE","PROJECT","SUPPLIER_PAYMENT","GOODS_RECEIPT","SUPPLIER_INVOICE","REQUISITION_PAYMENT_BATCH"],"type":"string"},"ownerId":{"type":"string","description":"The id of whatever this attachment belongs to — whichever owner column applies to `ownerType`."},"originalFileName":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"number"},"secureUrl":{"type":"string","description":"Cloudinary's secure URL — safe to render directly."},"caption":{"type":"string","nullable":true},"uploadedByMembershipId":{"type":"string","nullable":true,"description":"The membership that uploaded it. Null for a profile photo."},"latitude":{"type":"string","nullable":true,"example":"0.315700","description":"Capture latitude as a decimal string. Null unless this is project survey imagery."},"longitude":{"type":"string","nullable":true,"example":"32.581100","description":"Capture longitude as a decimal string. Null unless this is project survey imagery."},"capturedAt":{"format":"date-time","type":"string","nullable":true,"description":"When the image was captured on site. Null when not recorded. Distinct from `createdAt`, the upload time."},"createdAt":{"format":"date-time","type":"string"}},"required":["id","ownerType","ownerId","originalFileName","mimeType","sizeBytes","secureUrl","createdAt"]},"MembershipUserDto":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string","example":"Walter"},"lastName":{"type":"string","example":"Ruganzu"},"fullName":{"type":"string","example":"Walter Ruganzu","description":"Display name, derived from the parts — not stored, and not accepted on write."},"phoneCountryCode":{"type":"string","nullable":true,"example":"+256","description":"Dialling code, stored apart from the subscriber number."},"phone":{"type":"string","nullable":true,"example":"706700953","description":"Subscriber number — no country code, no leading zero."},"status":{"enum":["INVITED","ACTIVE","INACTIVE"],"type":"string"},"lastLoginAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"format":"date-time","type":"string"},"membershipStatus":{"enum":["ACTIVE","INACTIVE"],"type":"string","description":"Status of the membership."},"roles":{"description":"Roles held in this organization.","type":"array","items":{"type":"string"}}},"required":["id","email","firstName","lastName","fullName","status","createdAt","membershipStatus","roles"]},"CreateUserDto":{"type":"object","properties":{"email":{"type":"string","description":"Email address, unique platform-wide and used to sign in.","example":"quantity.surveyor@tetrabuild.example","format":"email"},"firstName":{"type":"string","description":"Given name.","example":"Walter","maxLength":100},"lastName":{"type":"string","description":"Family name.","example":"Ruganzu","maxLength":100},"password":{"type":"string","description":"Initial password. Omit to have Tetrabuild generate a temporary one and\nemail it to the user, the same way a password reset does — they sign in\nwith it and are required to choose their own password immediately after.","minLength":12,"maxLength":128},"phoneCountryCode":{"type":"string","description":"Dialling code including the leading `+`. Required when `phone` is given.","example":"+256"},"phone":{"type":"string","description":"Subscriber number only — no country code, no leading zero. Required when\n`phoneCountryCode` is given.","example":"706700953"},"roleIds":{"description":"Roles to grant in this organization.","uniqueItems":true,"type":"array","items":{"type":"string","format":"uuid"}},"defaultBranchId":{"type":"string","description":"Branch the user normally works from.","format":"uuid"}},"required":["email","firstName","lastName"]},"UpdateUserDto":{"type":"object","properties":{"firstName":{"type":"string","maxLength":100},"lastName":{"type":"string","maxLength":100},"phoneCountryCode":{"type":"string","nullable":true,"description":"Dialling code, or `null` to clear the number.","example":"+256"},"phone":{"type":"string","nullable":true,"description":"Subscriber number, or `null` to clear the number.","example":"706700953"}}},"SetUserStatusDto":{"type":"object","properties":{"status":{"type":"string","enum":["INVITED","ACTIVE","INACTIVE"]}},"required":["status"]},"InviteMemberDto":{"type":"object","properties":{"email":{"type":"string","description":"Address to invite. The response is identical whether or not this address\nalready has an account, so it cannot be probed for registered users.","example":"surveyor@partner.example","format":"email"},"roleId":{"type":"string","description":"Role to grant on acceptance. Must belong to this organization.","format":"uuid"}},"required":["email"]},"IssuedInvitationDto":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"enum":["PENDING","ACCEPTED","REVOKED"],"type":"string"},"expiresAt":{"format":"date-time","type":"string"},"roleId":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"token":{"type":"string","description":"Invitation token, returned once at creation and never again. Pass it to the invitee out of band."}},"required":["id","email","status","expiresAt","createdAt","token"]},"InvitationDto":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"enum":["PENDING","ACCEPTED","REVOKED"],"type":"string"},"expiresAt":{"format":"date-time","type":"string"},"roleId":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"}},"required":["id","email","status","expiresAt","createdAt"]},"AcceptInvitationDto":{"type":"object","properties":{"token":{"type":"string","description":"Token from the invitation."}},"required":["token"]},"UpdateMembershipDto":{"type":"object","properties":{"status":{"type":"string","description":"Suspends or restores access to this organization.","enum":["ACTIVE","INACTIVE"]},"defaultBranchId":{"type":"string","nullable":true,"format":"uuid"}}},"AssignRolesDto":{"type":"object","properties":{"roleIds":{"description":"The complete set of roles the member should hold. Replaces the existing\nassignment rather than adding to it, so a role is removed by omitting it.","uniqueItems":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["roleIds"]},"RoleDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"isSystem":{"type":"boolean","description":"System roles are created at bootstrap and cannot be renamed or deleted, so an organization cannot remove its only administrator role."},"permissions":{"description":"Permission keys granted.","type":"array","items":{"type":"string"}}},"required":["id","organizationId","name","isSystem","permissions"]},"CreateRoleDto":{"type":"object","properties":{"name":{"type":"string","description":"Role name, unique within the organization.","example":"Site Manager","maxLength":100},"description":{"type":"string","maxLength":255},"permissionKeys":{"description":"Permission keys this role grants. Must be keys that exist; unknown keys\nare rejected rather than silently ignored.","uniqueItems":true,"type":"array","items":{"type":"string"}}},"required":["name"]},"UpdateRoleDto":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":255},"permissionKeys":{"description":"Replaces the role's permissions entirely when supplied.","uniqueItems":true,"type":"array","items":{"type":"string"}}}},"PermissionDto":{"type":"object","properties":{"key":{"type":"string","example":"user.create"},"module":{"type":"string","example":"identity"},"description":{"type":"string"}},"required":["key","module","description"]},"CreateOrganizationDto":{"type":"object","properties":{"name":{"type":"string","description":"Registered or trading name of the business.","example":"Tetrabuild Construction Ltd","maxLength":200},"code":{"type":"string","description":"Short identifier used in documents and references. Uppercased on save,\nand treated as immutable afterwards because external references depend\non it.","example":"TETRA","minLength":2,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$"}},"required":["name","code"]},"OrganizationDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","description":"Immutable short identifier."},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"timezone":{"type":"string","description":"IANA timezone the organization works in. Show instants in it; reports date timestamps in it.","example":"Africa/Kampala"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","code","status","timezone","createdAt","updatedAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current 1-based page number.","example":1},"limit":{"type":"number","description":"Maximum items per page.","example":25},"total":{"type":"number","description":"Total items matching the query across all pages.","example":137},"totalPages":{"type":"number","description":"Total number of pages.","example":6},"hasNext":{"type":"boolean","description":"Whether a further page exists.","example":true}},"required":["page","limit","total","totalPages","hasNext"]},"PaginatedDto":{"type":"object","properties":{"items":{"description":"Declared explicitly as an untyped array.\n\nWithout an `@ApiProperty`, the Swagger CLI plugin infers metadata from the\nTypeScript type — and an unresolved generic `T[]` reads to it as a\ncircular dependency, which aborts document generation at startup.\n`@ApiPaginatedResponse` composes the concrete item schema over this, so\nnothing is lost by leaving it opaque here.","additionalProperties":true,"type":"array","items":{"type":"object"}},"meta":{"$ref":"#/components/schemas/PaginationMetaDto"}},"required":["items","meta"]},"UpdateOrganizationDto":{"type":"object","properties":{"name":{"type":"string","description":"Registered or trading name.","maxLength":200},"status":{"type":"string","description":"Deactivating an organization prevents its members from signing in to it.\nThe record and all its history are retained.","enum":["ACTIVE","INACTIVE"]},"timezone":{"type":"string","description":"IANA region timezone the organization works in. Changes the calendar day\nreports file an approval under, and the zone clients show times in.\nMatched case-insensitively and stored in canonical casing.","example":"Africa/Nairobi"}}},"CreateBranchDto":{"type":"object","properties":{"name":{"type":"string","description":"Branch or site name.","example":"Northern Depot","maxLength":200},"code":{"type":"string","description":"Short identifier, unique within the organization. Two organizations may\neach have a branch coded \"HQ\".","example":"NTH","minLength":2,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$"},"description":{"type":"string","description":"Optional location detail. All optional so existing integrations that send\nonly name and code keep working.","example":"Plot 42, Jinja Road","maxLength":500},"address":{"type":"string","maxLength":500},"city":{"type":"string","example":"Kampala","maxLength":120},"country":{"type":"string","example":"Uganda","maxLength":120}},"required":["name","code"]},"BranchDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"description":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}},"required":["id","organizationId","name","code","status"]},"UpdateBranchDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"status":{"type":"string","description":"Closing a branch deactivates it. Cost allocations and stock movements that\nreference it remain valid.","enum":["ACTIVE","INACTIVE"]},"description":{"type":"string","description":"Optional location detail. All optional so existing integrations that send\nonly name and code keep working.","example":"Plot 42, Jinja Road","maxLength":500},"address":{"type":"string","maxLength":500},"city":{"type":"string","example":"Kampala","maxLength":120},"country":{"type":"string","example":"Uganda","maxLength":120}}},"DepartmentDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","description":"Always the caller’s own organization."},"name":{"type":"string"},"code":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","name","code","status","createdAt","updatedAt"]},"CreateDepartmentDto":{"type":"object","properties":{"name":{"type":"string","description":"Department name.","example":"Quantity Surveying","maxLength":200},"code":{"type":"string","description":"Short identifier, unique within your organization. Normalised to upper\ncase, so `qs`, `QS` and ` QS ` are the same code rather than three.","example":"QS","minLength":2,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$"},"description":{"type":"string","description":"Optional description of what the department covers.","example":"Measurement, valuation and cost control","maxLength":500}},"required":["name","code"]},"UpdateDepartmentDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"status":{"type":"string","description":"Deactivating a department hides it from new selections while leaving every\nhistorical reference intact. There is no delete.","enum":["ACTIVE","INACTIVE"]}}},"CostCentreDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","description":"Always the caller’s own organization."},"name":{"type":"string"},"code":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","name","code","status","createdAt","updatedAt"]},"CreateCostCentreDto":{"type":"object","properties":{"name":{"type":"string","description":"Cost centre name.","example":"Construction Operations","maxLength":200},"code":{"type":"string","description":"Short identifier, unique within your organization. Normalised to upper\ncase on input.","example":"CC-CONSTRUCTION","minLength":2,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$"},"description":{"type":"string","description":"What expenditure this cost centre groups.","example":"Site works, plant and construction labour","maxLength":500}},"required":["name","code"]},"UpdateCostCentreDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"status":{"type":"string","description":"Deactivating a cost centre stops it being selected for new spend while\nleaving historical cost allocations intact. There is no delete.","enum":["ACTIVE","INACTIVE"]}}},"RequisitionTypeUsageDto":{"type":"object","properties":{"lineCount":{"type":"number","description":"Lines of every status that carry this type."},"submittedLineCount":{"type":"number","description":"Lines on requisitions already submitted (anything but a draft). These keep their route if the type’s route changes."}},"required":["lineCount","submittedLineCount"]},"RequisitionTypeDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","description":"Always the caller’s own organization."},"name":{"type":"string"},"code":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"category":{"enum":["GENERAL","VEHICLE"],"type":"string"},"isReceivable":{"type":"boolean","description":"Whether goods or work can arrive against a purchase order raised from this type. False for types that are settled rather than delivered, such as a cash advance."},"route":{"enum":["STOCK","PURCHASE","PAY"],"type":"string","description":"What happens to lines of this type after approval. Copied onto each line when its requisition is submitted."},"sortOrder":{"type":"number"},"updatedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"updatedByName":{"type":"string","nullable":true,"description":"Only with `include=usage`."},"usage":{"description":"Only with `include=usage`.","allOf":[{"$ref":"#/components/schemas/RequisitionTypeUsageDto"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","name","code","status","category","isReceivable","route","sortOrder","createdAt","updatedAt"]},"CreateRequisitionTypeDto":{"type":"object","properties":{"name":{"type":"string","description":"Requisition type name.","example":"Vehicle","maxLength":200},"code":{"type":"string","description":"Short identifier, unique within your organization. Normalised to upper\ncase on input.","example":"VEHICLE","minLength":2,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$"},"description":{"type":"string","description":"What this type of request covers.","example":"Vehicle hire, servicing and running costs","maxLength":500},"category":{"type":"string","description":"What this type BEHAVES as. Defaults to `GENERAL` — the ordinary\nline-items-against-a-budget-line shape — when omitted. Set to `VEHICLE`\nto have requisitions of this type carry a vehicle detail record instead\nof lines. Unlike `name` and `code`, this changes what the API accepts on\n`POST /projects/{id}/requisitions`.","enum":["GENERAL","VEHICLE"]},"isReceivable":{"type":"boolean","description":"Whether goods or work can arrive against a purchase order raised from this\ntype. Defaults to `true` when omitted.\n\nSet it to `false` for a type that is settled rather than delivered — a cash\nadvance, petty cash, a disbursement. Goods receipts cannot be opened against\norders of a non-receivable type. Independent of `category`, which governs\nthe form shape rather than what happens after the order is placed."},"route":{"type":"string","description":"What happens to lines of this type after approval. Defaults to `STOCK`.\nSetting anything else needs `requisition_type.manage`.","enum":["STOCK","PURCHASE","PAY"]},"sortOrder":{"type":"number","description":"Position within its route group on the New Requisition form.","minimum":0,"maximum":1000000}},"required":["name","code"]},"UpdateRequisitionTypeDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"status":{"type":"string","description":"Deactivating a requisition type stops it being selected on new\nrequisitions while leaving existing ones intact. There is no delete.","enum":["ACTIVE","INACTIVE"]},"category":{"type":"string","description":"Reclassifying an existing type changes what future requisitions of this\n type must submit — it never rewrites requisitions that already exist.","enum":["GENERAL","VEHICLE"]},"isReceivable":{"type":"boolean","description":"Changing this affects orders received from now on. It never rewrites goods\nreceipts that already exist — a receipt is a record of something that\nphysically happened, and reclassifying the type does not unhappen it."},"route":{"type":"string","description":"Changing the route needs `requisition_type.manage`. Applies to\nrequisitions submitted from now on: lines already submitted keep the\nroute they were submitted with.","enum":["STOCK","PURCHASE","PAY"]},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}}},"RouteImpactDto":{"type":"object","properties":{"submittedLineCount":{"type":"number","description":"Lines of this type on requisitions already submitted. They keep their current route."}},"required":["submittedLineCount"]},"RequisitionRouteSettingsDto":{"type":"object","properties":{"routesEnabled":{"type":"boolean","description":"`procurement.routes_enabled`. While false, every line is submitted as STOCK and Payments to make is hidden."}},"required":["routesEnabled"]},"UpdateRequisitionRouteSettingsDto":{"type":"object","properties":{"routesEnabled":{"type":"boolean"}},"required":["routesEnabled"]},"StaffAssignmentDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"departmentId":{"type":"string","format":"uuid"},"departmentCode":{"type":"string","example":"QS"},"departmentName":{"type":"string","example":"Quantity Surveying"},"isPrimary":{"type":"boolean","description":"Whether this member’s work is attributed to this department by default."},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"}},"required":["id","departmentId","departmentCode","departmentName","isPrimary","status"]},"StaffMemberDto":{"type":"object","properties":{"organizationMembershipId":{"type":"string","format":"uuid","description":"The membership id — the tenant-safe way to name a person within one organization."},"userId":{"type":"string","format":"uuid"},"fullName":{"type":"string","example":"Achieng Okello"},"email":{"type":"string","example":"a.okello@example.com"},"profilePhotoUrl":{"type":"string","nullable":true,"description":"The person’s profile photo, null when they have not uploaded one. The same photo `/auth/me` returns."},"jobTitle":{"type":"string","nullable":true,"example":"Quantity Surveyor"},"employeeNumber":{"type":"string","nullable":true,"example":"EMP-0231"},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string","description":"Membership status."},"departments":{"description":"Active and inactive departmental assignments. Empty for a member whose department has never been recorded.","type":"array","items":{"$ref":"#/components/schemas/StaffAssignmentDto"}}},"required":["organizationMembershipId","userId","fullName","email","status","departments"]},"OrgChartDepartmentDto":{"type":"object","properties":{"departmentId":{"type":"string","format":"uuid"},"code":{"type":"string","example":"QS"},"name":{"type":"string","example":"Quantity Surveying"},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"headMembershipId":{"type":"string","nullable":true,"format":"uuid"},"headName":{"type":"string","nullable":true,"example":"Achieng Okello"},"headAssignmentInactive":{"type":"boolean","description":"True when the named head no longer has an active assignment to this department. Surfaced rather than silently cleared, so a reshuffle does not quietly decapitate departments."},"memberCount":{"type":"number","description":"Members with an ACTIVE assignment here."}},"required":["departmentId","code","name","status","headAssignmentInactive","memberCount"]},"AssignDepartmentDto":{"type":"object","properties":{"departmentId":{"type":"string","description":"Department to assign this member to. Must belong to your organization and\nbe ACTIVE — assigning into a retired department would create a reference\nnobody can act on.","example":"3f2504e0-4f89-11d3-9a0c-0305e82c3301","format":"uuid"},"isPrimary":{"type":"boolean","description":"Make this the member's primary department — the one their work is\nattributed to by default.\n\nAt most one active assignment per member may be primary; setting this on a\nsecond one moves the flag rather than failing, because \"which department\ndoes this person mainly work in\" has exactly one answer and making the\ncaller clear the old one first would be ceremony.","example":true}},"required":["departmentId"]},"UpdateStaffAssignmentDto":{"type":"object","properties":{"isPrimary":{"type":"boolean"},"status":{"type":"string","description":"Ending an assignment sets INACTIVE rather than deleting it, so who worked\nin which department, and when, stays answerable. There is no delete.","enum":["ACTIVE","INACTIVE"]}}},"UpdateEmploymentDto":{"type":"object","properties":{"jobTitle":{"type":"string","description":"Job title, as the firm would print it in a directory. Free text — there is\nno controlled vocabulary, deliberately.\n\nTrimmed before validation, which is load-bearing rather than cosmetic:\n`@IsNotEmpty` accepts `\"   \"` because it is not the empty string, so\nwithout this a whitespace-only title would pass validation and be rejected\nby `ck_organization_membership_job_title_not_blank` — surfacing a database\nerror as a 500 where the honest answer is a 400.","example":"Quantity Surveyor","maxLength":150},"employeeNumber":{"type":"string","description":"The firm's own reference number for this member. Unique within your\norganization. Not normalised, because firms use mixed formats and\nrewriting what somebody typed onto a document would be worse than\naccepting it.\nTrimmed, for the same reason as `jobTitle` above — and additionally so\nthat ` EMP-1` and `EMP-1` cannot become two rows that the unique index\nconsiders distinct.","example":"EMP-0231","maxLength":50}}},"SetDepartmentHeadDto":{"type":"object","properties":{"headMembershipId":{"type":"string","nullable":true,"description":"Membership to name as head, or `null` to record a vacancy.\n\nMust have an active assignment to this department — a head who does not\nwork there would make the org chart lie. Naming somebody grants them\nnothing.","example":"3f2504e0-4f89-11d3-9a0c-0305e82c3301","format":"uuid"}},"required":["headMembershipId"]},"ProjectDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","description":"Always the caller’s own organization."},"projectCode":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"clientName":{"type":"string","nullable":true},"contractReference":{"type":"string","nullable":true},"branchId":{"type":"string","nullable":true,"format":"uuid"},"branchName":{"type":"string","nullable":true,"description":"Branch name, flattened so a list needs no second request."},"costCentreId":{"type":"string","nullable":true,"format":"uuid"},"costCentreName":{"type":"string","nullable":true},"responsibleDepartmentId":{"type":"string","nullable":true,"format":"uuid"},"responsibleDepartmentName":{"type":"string","nullable":true},"startDate":{"type":"string","nullable":true,"example":"2026-03-01","description":"Calendar date, `YYYY-MM-DD`."},"plannedCompletionDate":{"type":"string","nullable":true,"example":"2027-06-30"},"actualCompletionDate":{"type":"string","nullable":true,"example":"2027-05-14"},"contractValue":{"type":"string","nullable":true,"example":"1250000.00","description":"Decimal string, never a number — preserves exactness for large values."},"currency":{"type":"string","nullable":true,"example":"UGX"},"status":{"enum":["PLANNED","ACTIVE","ON_HOLD","COMPLETED","CANCELLED"],"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectCode","name","status","createdAt","updatedAt"]},"CreateProjectDto":{"type":"object","properties":{"projectCode":{"type":"string","description":"Business identifier, unique within your organization. Normalised to upper\ncase, so `kroc-001` and `KROC-001` are the same project.","example":"KROC-001","minLength":2,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$"},"name":{"type":"string","description":"Project name.","example":"Kampala Road Office Complex","maxLength":200},"description":{"type":"string","maxLength":1000},"clientName":{"type":"string","description":"Client as free text. A full customer domain belongs to CRM.","example":"ABC Holdings","maxLength":200},"contractReference":{"type":"string","description":"Contract or tender reference as quoted by the client.","example":"CTR-2026-014","maxLength":100},"branchId":{"type":"string","description":"Branch or site. Must belong to your organization.","format":"uuid"},"costCentreId":{"type":"string","description":"Cost centre. Must belong to your organization.","format":"uuid"},"responsibleDepartmentId":{"type":"string","description":"Department accountable for delivery. Must belong to your organization.","format":"uuid"},"startDate":{"type":"string","description":"Calendar date, `YYYY-MM-DD`. Not a timestamp: a project starts on a day,\nnot at an instant.","example":"2026-03-01"},"plannedCompletionDate":{"type":"string","example":"2027-06-30"},"contractValue":{"type":"string","description":"Contract value as a decimal **string**, never a JSON number — a number\nlarge enough for a UGX contract cannot be represented exactly.","example":"1250000.00"},"currency":{"type":"string","description":"ISO-4217 code. No conversion happens here.","example":"UGX"}},"required":["projectCode","name"]},"ProjectStatusCountsDto":{"type":"object","properties":{"PLANNED":{"type":"number"},"ACTIVE":{"type":"number"},"ON_HOLD":{"type":"number"},"COMPLETED":{"type":"number"},"CANCELLED":{"type":"number"}},"required":["PLANNED","ACTIVE","ON_HOLD","COMPLETED","CANCELLED"]},"ContractValueTotalDto":{"type":"object","properties":{"currency":{"type":"string","nullable":true,"description":"ISO 4217 code, or `null` for projects that declare no currency. Totals are never converted or combined across currencies.","example":"UGX"},"amount":{"type":"string","description":"Summed by the database, as a decimal string.","example":"18710000000.00"},"projectCount":{"type":"number","description":"Projects contributing to this total."}},"required":["amount","projectCount"]},"BudgetTotalDto":{"type":"object","properties":{"currency":{"type":"string","nullable":true,"example":"UGX"},"revisedAmount":{"type":"string","description":"Original amount plus variations, over ACTIVE budgets only.","example":"9800000000.00"},"actualIncurredAmount":{"type":"string","description":"Actual cost as recorded on budget lines. Entered by users — not reconciled against invoices or goods receipts.","example":"2150000000.00"},"projectCount":{"type":"number","description":"Projects with an ACTIVE budget in this currency."}},"required":["revisedAmount","actualIncurredAmount","projectCount"]},"CommittedTotalDto":{"type":"object","properties":{"currency":{"type":"string","nullable":true,"example":"UGX"},"amount":{"type":"string","description":"Value of ISSUED and CLOSED purchase orders — what the organization has committed itself to. Drafts and cancelled orders commit nothing.","example":"4100000000.0000"},"purchaseOrderCount":{"type":"number","description":"Committing purchase orders in this total."}},"required":["amount","purchaseOrderCount"]},"ProjectBudgetFigureDto":{"type":"object","properties":{"currency":{"type":"string","nullable":true},"revisedAmount":{"type":"string","example":"4500000000.00"},"actualIncurredAmount":{"type":"string","example":"1200000000.00"}},"required":["revisedAmount","actualIncurredAmount"]},"ProjectCommittedFigureDto":{"type":"object","properties":{"currency":{"type":"string","nullable":true},"amount":{"type":"string","example":"2100000000.0000"}},"required":["amount"]},"ProjectFinancialsDto":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"budget":{"nullable":true,"description":"The project’s ACTIVE budget, or `null` when it has none — or when the caller lacks `budget.view`.","type":"object","allOf":[{"$ref":"#/components/schemas/ProjectBudgetFigureDto"}]},"committed":{"nullable":true,"description":"Committed value per currency (empty when nothing is committed), or `null` when the caller lacks `purchase_order.view`.","type":"array","items":{"$ref":"#/components/schemas/ProjectCommittedFigureDto"}}},"required":["projectId"]},"ProjectSummaryDto":{"type":"object","properties":{"projectCount":{"type":"number","description":"Projects matching the filters."},"statusCounts":{"$ref":"#/components/schemas/ProjectStatusCountsDto"},"pastPlannedCompletionCount":{"type":"number","description":"ACTIVE projects whose planned completion date has passed without an actual completion date."},"contractValue":{"description":"Contract value per currency, excluding CANCELLED projects.","type":"array","items":{"$ref":"#/components/schemas/ContractValueTotalDto"}},"budget":{"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/BudgetTotalDto"}},"committed":{"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/CommittedTotalDto"}},"projects":{"description":"One entry per matching project, for a register to join by id.","type":"array","items":{"$ref":"#/components/schemas/ProjectFinancialsDto"}}},"required":["projectCount","statusCounts","pastPlannedCompletionCount","contractValue","projects"]},"UpdateProjectDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":1000},"clientName":{"type":"string","maxLength":200},"contractReference":{"type":"string","maxLength":100},"branchId":{"type":"string","format":"uuid"},"costCentreId":{"type":"string","format":"uuid"},"responsibleDepartmentId":{"type":"string","format":"uuid"},"startDate":{"type":"string"},"plannedCompletionDate":{"type":"string"},"contractValue":{"type":"string"},"currency":{"type":"string"},"expectedUpdatedAt":{"type":"string","description":"The `updatedAt` the edit was prepared against, exactly as it was read.\n\nWhen sent, the edit is refused with 409 `STALE_WRITE` — and nothing is\nwritten — if the project has been saved since. Omit it to keep the\nlast-write-wins behaviour.","example":"2026-09-28T09:14:03.120Z"}}},"ChangeProjectStatusDto":{"type":"object","properties":{"status":{"type":"string","description":"Target state. Only declared transitions are permitted.","enum":["PLANNED","ACTIVE","ON_HOLD","COMPLETED","CANCELLED"]},"actualCompletionDate":{"type":"string","description":"Completion date, required when moving to `COMPLETED` and rejected\notherwise — a project cannot be complete without a date, and a date\nwithout completion is meaningless.","example":"2027-05-14"}},"required":["status"]},"ProjectMemberDto":{"type":"object","properties":{"id":{"type":"string","description":"Id of the assignment itself."},"projectId":{"type":"string","format":"uuid"},"organizationMembershipId":{"type":"string","format":"uuid","description":"Membership that was assigned — scoped to this organization."},"userId":{"type":"string","format":"uuid","description":"The person’s global user id, for display and cross-referencing."},"firstName":{"type":"string","example":"Walter"},"lastName":{"type":"string","example":"Ruganzu"},"fullName":{"type":"string","example":"Walter Ruganzu","description":"Display name, derived from the parts."},"email":{"type":"string"},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string","description":"Status of **this assignment**. `INACTIVE` means the person is no longer assigned to the project."},"organizationMembershipStatus":{"enum":["ACTIVE","INACTIVE"],"type":"string","description":"Status of the person’s membership of the organization, reported separately and deliberately. A suspended member keeps their project assignments — the assignment is a record of who is on the job, not a grant of access — so showing both makes it clear whether someone is off this project or out of the organization entirely."},"userStatus":{"enum":["INVITED","ACTIVE","INACTIVE"],"type":"string","description":"Status of the underlying user account."},"assignedAt":{"format":"date-time","type":"string","description":"When the person was first assigned to this project."}},"required":["id","projectId","organizationMembershipId","userId","firstName","lastName","fullName","email","status","organizationMembershipStatus","userStatus","assignedAt"]},"AssignProjectMemberDto":{"type":"object","properties":{"organizationMembershipId":{"type":"string","description":"Membership of the person to assign, from\n`GET /organizations/{organizationId}/... ` or the users list.","format":"uuid"}},"required":["organizationMembershipId"]},"UpdateProjectMemberDto":{"type":"object","properties":{"status":{"type":"string","enum":["ACTIVE","INACTIVE"]}},"required":["status"]},"RequestProjectReopenDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000,"example":"Marked completed by mistake; snagging still in progress"}},"required":["reason"]},"ProjectReopenRequestDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"projectCode":{"type":"string"},"projectName":{"type":"string"},"status":{"enum":["PENDING","APPROVED","REJECTED"],"type":"string"},"reason":{"type":"string"},"previousCompletionDate":{"type":"string","nullable":true,"example":"2026-11-10"},"requestedByMembershipId":{"type":"string","format":"uuid"},"requestedByName":{"type":"string","nullable":true},"requestedAt":{"format":"date-time","type":"string"},"decidedByName":{"type":"string","nullable":true},"decidedAt":{"format":"date-time","type":"string","nullable":true},"decisionNote":{"type":"string","nullable":true},"isMine":{"type":"boolean","description":"True when the caller made the request, so cannot approve it."}},"required":["id","projectId","projectCode","projectName","status","reason","previousCompletionDate","requestedByMembershipId","requestedByName","requestedAt","decidedByName","decidedAt","decisionNote","isMine"]},"ProjectReopenDecisionDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000,"example":"The project is finished"}},"required":["reason"]},"BoqImportIssueDto":{"type":"object","properties":{"sheet":{"type":"string","example":"Items","description":"Worksheet name; empty for a problem with the file itself."},"row":{"type":"number","example":14,"description":"1-based spreadsheet row. 1 is the header row; 0 means the whole file or sheet."},"column":{"type":"string","example":"Rate","description":"Column header, when the problem is one cell."},"message":{"type":"string","example":"Rate \"45,000.123456\" must be a non-negative number with at most 14 digits before the decimal point and 4 after it."}},"required":["sheet","row","message"]},"BoqImportResultDto":{"type":"object","properties":{"dryRun":{"type":"boolean","description":"True when nothing was written because `dryRun` was set."},"valid":{"type":"boolean","description":"True when the file has no problems."},"sectionsCreated":{"type":"number","example":12,"description":"Sections created — or, on a dry run, that would be created. 0 when invalid."},"itemsCreated":{"type":"number","example":184,"description":"Items created — or, on a dry run, that would be created. 0 when invalid."},"importedAmount":{"type":"string","example":"1284350000.0000","description":"Exact sum of the imported lines’ amounts, as a decimal string."},"errorCount":{"type":"number","description":"Total number of problems, even beyond the 500 returned."},"errors":{"description":"Sorted by sheet, then row. At most 500.","type":"array","items":{"$ref":"#/components/schemas/BoqImportIssueDto"}}},"required":["dryRun","valid","sectionsCreated","itemsCreated","importedAmount","errorCount","errors"]},"BoqDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","description":"Always the caller’s own organization."},"projectId":{"type":"string","format":"uuid"},"boqCode":{"type":"string","example":"MAIN"},"name":{"type":"string","example":"Main Contract Bill of Quantities"},"description":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true,"example":"UGX"},"status":{"enum":["DRAFT","ACTIVE","CLOSED"],"type":"string"},"totalAmount":{"type":"string","description":"Sum of all item amounts in this bill, as a decimal string with 4 decimal places. Derived, never stored. `0.0000` for an empty bill.","example":"3250000.5000"},"itemCount":{"type":"number","example":42,"description":"Number of items in this bill."},"sectionCount":{"type":"number","example":7,"description":"Number of sections in this bill, at every level."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","boqCode","name","status","totalAmount","itemCount","sectionCount","createdAt","updatedAt"]},"UpdateBoqDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":1000},"currency":{"type":"string"}}},"ChangeBoqStatusDto":{"type":"object","properties":{"status":{"type":"string","description":"Target state. Only declared transitions are permitted.","enum":["DRAFT","ACTIVE","CLOSED"]}},"required":["status"]},"BoqSectionTreeDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","description":"Always the caller’s own organization."},"boqId":{"type":"string","format":"uuid"},"parentSectionId":{"type":"string","nullable":true,"format":"uuid","description":"`null` for a root section. Changed only by the move endpoint."},"sectionCode":{"type":"string","example":"02.01"},"name":{"type":"string","example":"Substructure"},"description":{"type":"string","nullable":true},"sortOrder":{"type":"number","example":10,"description":"Position among siblings. Sections are ordered by this, then by `sectionCode`, then by `id`."},"depth":{"type":"number","example":1,"description":"Distance from the root: 0 for a root section, capped at 9."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"subtotalAmount":{"type":"string","description":"Subtree total as a decimal string: this section’s items plus every descendant’s. `0.0000` when the subtree holds no items.","example":"3250000.5000"},"itemCount":{"type":"number","example":12,"description":"Item count for this section and all its descendants."},"children":{"description":"Child sections, in order. Empty for a leaf.","type":"array","items":{"$ref":"#/components/schemas/BoqSectionTreeDto"}}},"required":["id","organizationId","boqId","sectionCode","name","sortOrder","depth","createdAt","updatedAt","subtotalAmount","itemCount","children"]},"CreateBoqSectionDto":{"type":"object","properties":{"sectionCode":{"type":"string","description":"Structural identifier as the surveyor writes it. Unique within the bill\nand immutable once set. Case is preserved.","example":"02.01","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9._/-]+$"},"name":{"type":"string","description":"Section title.","example":"Substructure","maxLength":200},"description":{"type":"string","maxLength":1000},"parentSectionId":{"type":"string","description":"Parent section, omitted for a root section (what a printed bill calls\n\"Bill 01\"). Must belong to the same bill.\n\n**Set once and never changed** — there is no re-parenting operation, which\nis what makes a cycle in the hierarchy unreachable rather than merely\nguarded against.","format":"uuid"},"sortOrder":{"type":"number","description":"Position among siblings. Defaults to the end of the list — the highest\nexisting position plus ten, leaving gaps to insert into later.\n\nDistinct from `sectionCode`: a code is an identifier, position is a\nseparate fact. Sections are listed by position first, then by code.","example":10,"minimum":0,"maximum":1000000000}},"required":["sectionCode","name"]},"BoqSectionDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","description":"Always the caller’s own organization."},"boqId":{"type":"string","format":"uuid"},"parentSectionId":{"type":"string","nullable":true,"format":"uuid","description":"`null` for a root section. Changed only by the move endpoint."},"sectionCode":{"type":"string","example":"02.01"},"name":{"type":"string","example":"Substructure"},"description":{"type":"string","nullable":true},"sortOrder":{"type":"number","example":10,"description":"Position among siblings. Sections are ordered by this, then by `sectionCode`, then by `id`."},"depth":{"type":"number","example":1,"description":"Distance from the root: 0 for a root section, capped at 9."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","boqId","sectionCode","name","sortOrder","depth","createdAt","updatedAt"]},"UpdateBoqSectionDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":1000},"sortOrder":{"type":"number","minimum":0,"maximum":1000000000}}},"MoveBoqSectionDto":{"type":"object","properties":{"parentSectionId":{"type":"string","nullable":true,"description":"The new parent, in the same bill — or `null` to make the section a root.\nRequired, so \"move to the top level\" is always said explicitly.","format":"uuid"},"sortOrder":{"type":"number","description":"Position among the new siblings. Defaults to the end of the list.","minimum":0,"maximum":1000000000}},"required":["parentSectionId"]},"BoqItemDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","description":"Always the caller’s own organization."},"boqId":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid","description":"Changeable through PATCH, within the same bill."},"sectionCode":{"type":"string","nullable":true,"description":"Section code, flattened so an item list needs no second request."},"itemCode":{"type":"string","example":"02.01.03","description":"Immutable once set."},"description":{"type":"string","example":"Reinforced concrete class C25/30 in foundations"},"unit":{"type":"string","example":"m3"},"quantity":{"type":"string","example":"127.5000","description":"Decimal string with 4 decimal places, never a number."},"rate":{"type":"string","example":"25000.0000"},"amount":{"type":"string","description":"Server-calculated `quantity × rate`, exact to 4 decimal places. Read-only: sending it returns 400, and it is recomputed by the database on every change to quantity or rate.","example":"3187500.0000"},"sortOrder":{"type":"number","example":10,"description":"Position within the section. Items are ordered by this, then by `itemCode`, then by `id`."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","boqId","sectionId","itemCode","description","unit","quantity","rate","amount","sortOrder","createdAt","updatedAt"]},"CreateBoqItemDto":{"type":"object","properties":{"itemCode":{"type":"string","description":"The surveyor's line number, unique within the bill and immutable once set.\n\nCase is **preserved**, unlike `boqCode`: this is a contractual reference in\nthe surveyor's own notation, and folding `02.01.03a` to `02.01.03A` would\nalter what appears in a signed bill.","example":"02.01.03","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9._/-]+$"},"description":{"type":"string","description":"The measured description of work, as it reads in the bill.","example":"Reinforced concrete class C25/30 in foundations","maxLength":2000},"unit":{"type":"string","description":"Unit of measurement, free text — `m`, `m2`, `m3`, `kg`, `tonne`, `sum`,\n`item`, `no`, `day`. Not a fixed list: construction's unit vocabulary has\na long tail.","example":"m3","maxLength":16},"quantity":{"type":"string","description":"Measured quantity as a decimal **string**, never a JSON number — a number\nhas already passed through a double and lost exactness before the server\nsees it.\n\nAt most 14 integer and 4 decimal digits, which is exactly what\n`numeric(18,4)` holds, so an oversized value is a 400 here rather than an\noverflow inside PostgreSQL.","example":"127.5"},"rate":{"type":"string","description":"Unit rate as a decimal **string**, in the bill's currency.","example":"25000.00"},"sortOrder":{"type":"number","description":"Position within the section. Defaults to the end of the list.","example":10,"minimum":0,"maximum":1000000000}},"required":["itemCode","description","unit","quantity","rate"]},"UpdateBoqItemDto":{"type":"object","properties":{"sectionId":{"type":"string","description":"Moves the item to another section **of the same bill**. Without an explicit\n`sortOrder` it lands at the end of the new section.","format":"uuid"},"description":{"type":"string","maxLength":2000},"unit":{"type":"string","maxLength":16},"quantity":{"type":"string"},"rate":{"type":"string"},"sortOrder":{"type":"number","minimum":0,"maximum":1000000000}}},"CreateBoqDto":{"type":"object","properties":{"boqCode":{"type":"string","description":"Bill identifier, unique within the project. Normalised to upper case, so\n`main` and `MAIN` are the same bill.","example":"MAIN","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9._/-]+$"},"name":{"type":"string","description":"Bill name.","example":"Main Contract Bill of Quantities","maxLength":200},"description":{"type":"string","maxLength":1000},"currency":{"type":"string","description":"ISO-4217 code the bill's rates are expressed in. No conversion happens\nhere.","example":"UGX"}},"required":["boqCode","name"]},"BudgetDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","description":"Always the caller’s own organization."},"projectId":{"type":"string","format":"uuid"},"budgetCode":{"type":"string","example":"MAIN","description":"Immutable once set."},"name":{"type":"string","example":"Main Contract Budget"},"description":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true,"example":"UGX"},"status":{"enum":["DRAFT","ACTIVE","CLOSED"],"type":"string","description":"Changed only through PATCH /budgets/{id}/status. At most one ACTIVE budget per project."},"totalAmount":{"type":"string","description":"Server-calculated SUM of line amounts, exact to 2 decimal places. Read-only and derived — it cannot be set, and cannot disagree with the lines.","example":"1250000000.00"},"totalVariationAmount":{"type":"string","example":"120000000.00","description":"Sum of the lines’ `variationAmount`. **May be negative.** Derived on read."},"totalActualIncurredAmount":{"type":"string","example":"1894000000.00","description":"Sum of the lines’ `actualIncurredAmount`. Derived on read. These are ENTERED figures, not reconciled against invoices — see `BudgetLineDto.actualIncurredAmount`."},"totalForecastAmount":{"type":"string","example":"4715000000.00","description":"Sum of the lines’ `forecastAmount`. Derived on read."},"totalRevisedAmount":{"type":"string","example":"4970000000.00","description":"DERIVED: `totalAmount + totalVariationAmount` — the budget actually in force."},"totalVarianceAmount":{"type":"string","example":"-255000000.00","description":"DERIVED: `totalForecastAmount − totalRevisedAmount`. **Negative is under budget**, i.e. favourable."},"lineCount":{"type":"number","example":42,"description":"Number of lines in this budget."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","budgetCode","name","status","totalAmount","totalVariationAmount","totalActualIncurredAmount","totalForecastAmount","totalRevisedAmount","totalVarianceAmount","lineCount","createdAt","updatedAt"]},"UpdateBudgetDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":1000},"currency":{"type":"string"}}},"ChangeBudgetStatusDto":{"type":"object","properties":{"status":{"type":"string","description":"Target state. `DRAFT → ACTIVE, CLOSED`; `ACTIVE → CLOSED`; `CLOSED` is\nterminal. Anything else returns 409 naming the legal moves. Setting the\ncurrent status again succeeds unchanged, so retrying an applied request\ndoes not fail.\n\nActivating is refused with 409 when the project already has another\n`ACTIVE` budget — at most one budget authorizes spending at a time.","enum":["DRAFT","ACTIVE","CLOSED"]}},"required":["status"]},"BudgetLineExposureDto":{"type":"object","properties":{"authorizedAmount":{"type":"string","example":"1250000000.00","description":"What the budget line authorizes: its REVISED amount, `amount + variationAmount` — the original award plus any variation orders. A negative variation reduces it."},"requestedAmount":{"type":"string","example":"1617000.0000","description":"Sum of estimated amounts on **SUBMITTED** requisition lines drawing against this budget line. DRAFT and CANCELLED requests are excluded: an abandoned draft must not depress available budget, and a withdrawn request asks for nothing. An estimate at 4 decimal places, not a commitment."},"remainingAmount":{"type":"string","example":"1248383000.0000","description":"authorizedAmount − requestedAmount. **May be negative**, which is reported rather than refused — nothing here blocks an over-request."},"submittedLineCount":{"type":"number","example":2,"description":"Number of SUBMITTED requisition lines drawing against this budget line."}},"required":["authorizedAmount","requestedAmount","remainingAmount","submittedLineCount"]},"BudgetLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","description":"Always the caller’s own organization."},"budgetId":{"type":"string","format":"uuid","description":"Fixed at creation."},"projectId":{"type":"string","format":"uuid","description":"The budget’s project. Derived, never client-supplied."},"boqItemId":{"type":"string","nullable":true,"format":"uuid","description":"The BOQ item this line draws against; null for a line the bill does not measure, such as overheads or contingency."},"boqId":{"type":"string","nullable":true,"format":"uuid","description":"The bill the item belongs to. Derived from the item, never client-supplied; null exactly when boqItemId is."},"boqItemCode":{"type":"string","nullable":true,"example":"02.01.03","description":"The BOQ item’s code, joined in for display."},"boqItemDescription":{"type":"string","nullable":true,"description":"The BOQ item’s description, joined in for display."},"boqItemAmount":{"type":"string","nullable":true,"description":"The BOQ item’s current quantity × rate, at 4 decimal places, joined in for comparison against this line’s amount. Read-only.","example":"3187500.0000"},"costCentreId":{"type":"string","nullable":true,"format":"uuid"},"costCentreCode":{"type":"string","nullable":true,"example":"CC-CIVIL"},"costCentreName":{"type":"string","nullable":true},"description":{"type":"string","example":"Concrete to substructure, incl. 5% wastage allowance"},"amount":{"type":"string","example":"1250000000.00","description":"The authorized amount as a decimal string with 2 decimal places, never a number. The budget’s own figure — not derived from the BOQ item."},"variationAmount":{"type":"string","example":"52800000.00","description":"Signed value added by variation orders since award, at 2 decimal places. **May be negative** — a variation can omit work. Net position, not a history: a line varied twice reports one figure."},"actualIncurredAmount":{"type":"string","example":"412000000.00","description":"Costs incurred **other than through approved supplier invoices** (accruals, labour, petty cash), at 2 decimal places. **Entered, not derived.** Invoiced cost is `invoicedAmount`; the line’s actual cost is `totalActualAmount`."},"invoicedAmount":{"type":"string","example":"398500000.0000","description":"DERIVED: approved supplier invoice lines drawn on this budget line, net of tax, at 4 decimal places."},"requisitionActualAmount":{"type":"string","example":"8500.0000","description":"DERIVED: actual amounts recorded on the lines of `APPROVED` requisitions drawn on this budget line (`PUT /requisitions/{id}/actual-expenditure`), at 4 decimal places. Never overlaps `invoicedAmount`: a line on a live purchase order cannot carry a recorded actual."},"totalActualAmount":{"type":"string","example":"810508500.0000","description":"DERIVED: `invoicedAmount + requisitionActualAmount + actualIncurredAmount`."},"forecastAmount":{"type":"string","example":"910000000.00","description":"Expected final cost — a judgement, which is why it is stored rather than computed. Defaults to `amount` on create, so a line nobody has re-forecast reports a variance of zero rather than a 100% saving."},"revisedAmount":{"type":"string","example":"1302800000.00","description":"DERIVED: `amount + variationAmount` — the budget actually in force. Never stored, so it cannot disagree with its own operands. Guaranteed non-negative."},"varianceAmount":{"type":"string","example":"-135000000.00","description":"DERIVED: `forecastAmount − revisedAmount`. **Negative is under budget**, i.e. favourable. Signed so a client cannot render an over-run as a saving by subtracting the wrong way round."},"sortOrder":{"type":"number","example":10},"exposure":{"description":"What has been requested against this budget line by SUBMITTED requisitions. Derived on read and never stored; nothing here reserves or blocks budget.","allOf":[{"$ref":"#/components/schemas/BudgetLineExposureDto"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","budgetId","projectId","description","amount","variationAmount","actualIncurredAmount","invoicedAmount","requisitionActualAmount","totalActualAmount","forecastAmount","revisedAmount","varianceAmount","sortOrder","createdAt","updatedAt"]},"CreateBudgetLineDto":{"type":"object","properties":{"boqItemId":{"type":"string","description":"The BOQ item this line authorizes expenditure against.\n\nOptional. Omit it for expenditure the bill does not measure —\npreliminaries, site overheads, contingency, professional fees — which are\nordinary budget lines rather than an edge case.\n\nWhen supplied, the item must belong to the **same project** as this budget\nand to the caller's organization, and its bill must be `ACTIVE`. All three\nare checked by the service for a friendly error, and the first two are\nadditionally guaranteed by composite foreign keys, so a cross-project or\ncross-tenant line is unrepresentable rather than merely refused.","format":"uuid"},"costCentreId":{"type":"string","description":"Optional cost centre, for reporting expenditure by the organization's own\ncost structure. Must belong to the caller's organization.","format":"uuid"},"description":{"type":"string","description":"What this line authorizes, in words. Required even when `boqItemId` is\ngiven: it records the budgeting intent rather than repeating the bill's\nwording, and the item's own description is joined into reads anyway.","example":"Concrete to substructure, incl. 5% wastage allowance","maxLength":2000},"amount":{"type":"string","description":"The authorized amount as a decimal **string**, never a JSON number — a\nnumber has already passed through a double and lost exactness before the\nserver sees it, so one is rejected with a 400.\n\nAt most 16 integer and 2 decimal digits, which is exactly what\n`numeric(18,2)` holds, so an oversized value is a 400 here rather than a\n500 from PostgreSQL. Zero is accepted (a placeholder line); negative is\nnot.\n\nThis is the budget's **own** figure, deliberately not derived from the BOQ\nitem's `quantity × rate`. The bill measures work; the budget authorizes\nmoney, and keeping them independent is what makes a variance visible.","example":"1250000000.00"},"variationAmount":{"type":"string","description":"Signed value added by variation orders, as a decimal string. Defaults to\n`\"0.00\"`.\n\nThe one money field here that accepts a NEGATIVE value, because a\nvariation can omit work. `amount + variationAmount` may not fall below\nzero — refused with a 400 by the service, so the database is never first\nto reject it."},"actualIncurredAmount":{"type":"string","description":"Invoiced or accrued to date, as a decimal string. Defaults to `\"0.00\"`.\n\nENTERED, NOT DERIVED — nothing reconciles this against supplier invoices,\nbecause no invoice domain exists yet. It is deliberately not filled from\npurchase orders: an issued order is money promised, not money spent."},"forecastAmount":{"type":"string","description":"Expected final cost, as a decimal string.\n\nDefaults to `amount` when omitted, NOT to zero: a forecast of zero against\na real budget would report the line as a 100% saving."},"sortOrder":{"type":"number","description":"Presentation position within the budget. Defaults to `max + 10` among the\nbudget's lines, leaving gaps to insert into.","minimum":0,"maximum":1000000000}},"required":["description","amount"]},"UpdateBudgetLineDto":{"type":"object","properties":{"costCentreId":{"type":"string","format":"uuid"},"description":{"type":"string","maxLength":2000},"amount":{"type":"string"},"variationAmount":{"type":"string","description":"Signed. See {@link CreateBudgetLineDto.variationAmount}."},"actualIncurredAmount":{"type":"string","description":"Entered, not derived. See {@link CreateBudgetLineDto.actualIncurredAmount}."},"forecastAmount":{"type":"string","description":"Expected final cost.\n\nUnlike on create there is no defaulting here: omitting it leaves the\nexisting forecast alone. Re-basing a forecast onto a newly edited budget\nis a decision, not a side effect of changing the authorization."},"sortOrder":{"type":"number","minimum":0,"maximum":1000000000}}},"CreateBudgetTransferDto":{"type":"object","properties":{"fromLineId":{"type":"string","description":"The line giving up budget. Must belong to the budget in the path.","format":"uuid"},"toLineId":{"type":"string","description":"The line receiving it. Must belong to the same budget, and differ.","format":"uuid"},"amount":{"type":"string","description":"How much to move, as a decimal **string** — a JSON number is refused with\na 400, as on every money field. Strictly positive: a transfer of zero\nmoves nothing and would still write an audit event, and a negative one is\njust the transfer the other way round with the lines swapped.","example":"1000000.00"},"reason":{"type":"string","description":"Why the money is moving. Recorded as the audit event's description, so it\nis required and long enough to mean something.","example":"Re-allocating savings on substructure to external works","minLength":10,"maxLength":500},"reference":{"type":"string","description":"The instruction that authorizes the move — a variation order or site\ninstruction number. Blank is treated as absent.","example":"VO-014","maxLength":32},"adjustForecast":{"type":"boolean","description":"Whether the forecast follows the budget. Defaults to `true`: moving\nauthorization between lines should not, by itself, make one line look\nover budget and the other under.\n\nRead from the raw payload, so the string `\"false\"` is a 400 rather than\nbeing coerced to `true` by implicit conversion."}},"required":["fromLineId","toLineId","amount","reason"]},"BudgetTransferResultDto":{"type":"object","properties":{"from":{"description":"The line that gave up budget.","allOf":[{"$ref":"#/components/schemas/BudgetLineDto"}]},"to":{"description":"The line that received it.","allOf":[{"$ref":"#/components/schemas/BudgetLineDto"}]}},"required":["from","to"]},"CreateBudgetDto":{"type":"object","properties":{"budgetCode":{"type":"string","description":"Budget identifier, unique within the project. Normalised to upper case, so\n`main` and `MAIN` are the same budget.","example":"MAIN","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9._/-]+$"},"name":{"type":"string","description":"Budget name.","example":"Main Contract Budget","maxLength":200},"description":{"type":"string","maxLength":1000},"currency":{"type":"string","description":"ISO-4217 code the budget's amounts are expressed in. No conversion happens\nhere, and nothing sums across currencies.","example":"UGX"},"lines":{"description":"Lines to create with the budget, committed in the **same transaction** as\nthe header.\n\nOptional: a budget may be created empty and filled in afterwards. When\nsupplied, either everything commits or nothing does — a budget is financial\ninformation, and a header that survived while half its lines failed would\nbe a partial authorization that looks complete.","type":"array","items":{"$ref":"#/components/schemas/CreateBudgetLineDto"}}},"required":["budgetCode","name"]},"RequisitionTypeSummaryDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"category":{"enum":["GENERAL","VEHICLE"],"type":"string"},"route":{"enum":["STOCK","PURCHASE","PAY"],"type":"string"}},"required":["id","name","code","category","route"]},"RequisitionVehicleDetailDto":{"type":"object","properties":{"requisitionId":{"type":"string","format":"uuid","description":"Same id as its requisition."},"vehicleRegistrationNumber":{"type":"string"},"driverName":{"type":"string"},"fromLocation":{"type":"string"},"toLocation":{"type":"string"},"distanceKm":{"type":"string","example":"184.50"},"vehicleEngineSizeCc":{"type":"number","nullable":true},"litresRequired":{"type":"string","example":"45.00"},"departureDate":{"type":"string","example":"2026-03-01"},"returnDate":{"type":"string","example":"2026-03-03"},"passengerCount":{"type":"number"},"activityDescription":{"type":"string"},"comments":{"type":"string"}},"required":["requisitionId","vehicleRegistrationNumber","driverName","fromLocation","toLocation","distanceKm","litresRequired","departureDate","returnDate","passengerCount","activityDescription","comments"]},"RequisitionRejectionDto":{"type":"object","properties":{"reason":{"type":"string","example":"Rate is above the BOQ rate; requote with two suppliers.","description":"The approver’s reason. Always present: a rejection without one is refused."},"rejectedAt":{"type":"string","format":"date-time"},"rejectedByName":{"type":"string","nullable":true,"example":"Awino Okello","description":"Who rejected it, joined in for display."},"byOverride":{"type":"boolean","description":"True when an administrator rejected it under `approval.override` rather than the approver it was waiting on. `rejectedByName` is then the administrator."}},"required":["reason","rejectedAt","byOverride"]},"RequisitionFulfilmentDto":{"type":"object","properties":{"state":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","COMPLETED"]},"doneLines":{"type":"number","description":"Lines whose route has finished."},"totalLines":{"type":"number"},"summary":{"type":"string","example":"2 of 3 lines ordered · 1 paid"}},"required":["state","doneLines","totalLines","summary"]},"RequisitionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","description":"Always the caller’s own organization."},"projectId":{"type":"string","format":"uuid"},"requisitionNumber":{"type":"string","example":"REQ-0001","description":"Server-generated, sequential within the project, immutable once set."},"bookSerialNumber":{"type":"string","nullable":true,"example":"1822","description":"The paper requisition book’s pre-printed S/NO, when this record was transcribed from one. `null` for a requisition raised in the app. Unique per organization where present — a serial identifies one physical page."},"requestedByMembershipId":{"type":"string","format":"uuid","description":"The membership that raised the request. Derived from the authenticated session, never client-supplied."},"requestedByName":{"type":"string","nullable":true,"example":"Awino Okello","description":"The requester’s name, joined in for display."},"requestedByEmail":{"type":"string","nullable":true,"description":"The requester’s email, joined in for display."},"lastModifiedByMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"The membership that last changed the request’s header or lines — the requester, or an approver who corrected it while it was their turn. Null when nobody has edited it since it was raised. Status moves, attachments and budget-line placement at approval do not count."},"lastModifiedByName":{"type":"string","nullable":true,"example":"Awino Okello","description":"The last editor’s name, joined in for display."},"lastModifiedAt":{"format":"date-time","type":"string","nullable":true,"description":"When the request’s header or lines were last changed. Null when never edited since it was raised. See `requisition_updated` in the audit log for every edit and what it changed."},"requisitionTypeId":{"type":"string","format":"uuid","description":"The requisition type. For a requisition with lines this is the type of its **first line** — lines carry their own, and may differ; see `requisitionTypes`. For a VEHICLE requisition it is the vehicle type."},"requisitionType":{"$ref":"#/components/schemas/RequisitionTypeSummaryDto"},"requisitionTypes":{"description":"Every distinct type across its lines, in the order they first appear. Never empty: a requisition without lines lists its own `requisitionType`.","type":"array","items":{"$ref":"#/components/schemas/RequisitionTypeSummaryDto"}},"purpose":{"type":"string","example":"Blinding to substructure, pour scheduled Friday"},"needByDate":{"type":"string","nullable":true,"example":"2026-03-01","description":"Calendar date, `YYYY-MM-DD`."},"notes":{"type":"string","nullable":true},"departmentId":{"type":"string","nullable":true,"format":"uuid"},"departmentName":{"type":"string","nullable":true,"description":"The department’s name, joined in for display."},"projectName":{"type":"string","description":"The project’s name, joined in for display. Essential on the cross-project register, where `requisitionNumber` alone is ambiguous — it restarts at REQ-0001 in every project.","example":"Kampala Mall Development"},"projectCode":{"type":"string","description":"The project’s code, joined in the same way.","example":"KM-2026-001"},"currency":{"type":"string","nullable":true,"example":"UGX"},"preferredSupplierName":{"type":"string","nullable":true},"deliverTo":{"type":"string","nullable":true},"approverMembershipIds":{"nullable":true,"description":"Memberships named to approve this, in signing order. The requester’s choice, not the authority: once submitted, the route that governs the request is the frozen snapshot at GET /requisitions/{id}/approval, which this no longer affects. NULL when the requisition is routed by the organization’s approval policy instead.","type":"array","items":{"type":"string","format":"uuid"}},"vehicleDetail":{"nullable":true,"description":"Present when, and only when, this requisition’s type has category `VEHICLE`.","type":"object","allOf":[{"$ref":"#/components/schemas/RequisitionVehicleDetailDto"}]},"status":{"enum":["DRAFT","SUBMITTED","CANCELLED","APPROVED","REJECTED"],"type":"string","description":"Changed only through PATCH /requisitions/{id}/status. SUBMITTED and CANCELLED are locked against every edit."},"submittedAt":{"type":"string","nullable":true,"format":"date-time","description":"When the request was submitted. Never cleared."},"cancelledAt":{"type":"string","nullable":true,"format":"date-time","description":"When the request was cancelled. Never cleared."},"rejection":{"nullable":true,"description":"Why it was rejected, by whom and when. Null unless `status` is REJECTED; cleared once the request is edited back to DRAFT.","type":"object","allOf":[{"$ref":"#/components/schemas/RequisitionRejectionDto"}]},"approvalInProgress":{"type":"boolean","description":"True while the request is SUBMITTED and at least one approver has already approved it. Only the approver whose turn it is may edit it then; anybody else is refused with 409 `APPROVAL_IN_PROGRESS` until it is rejected."},"totalEstimatedAmount":{"type":"string","description":"Server-calculated SUM of line estimated amounts, exact to 4 decimal places. Read-only and derived — an estimate, never a commitment.","example":"3187500.0000"},"lineCount":{"type":"number","example":4,"description":"Number of lines on this request."},"fulfilment":{"nullable":true,"description":"How far an APPROVED requisition’s lines have got on their routes. Null unless at least one line is off the STOCK route, so a stock-only requisition reads exactly as before.","type":"object","allOf":[{"$ref":"#/components/schemas/RequisitionFulfilmentDto"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","requisitionNumber","requestedByMembershipId","requisitionTypeId","requisitionType","requisitionTypes","purpose","status","approvalInProgress","totalEstimatedAmount","lineCount","createdAt","updatedAt"]},"UpdateRequisitionDto":{"type":"object","properties":{"requisitionTypeId":{"type":"string","format":"uuid"},"bookSerialNumber":{"type":"string","description":"The paper book's S/NO. Correctable while the request is still `DRAFT`.","maxLength":32},"purpose":{"type":"string","maxLength":1000},"needByDate":{"type":"string"},"notes":{"type":"string","maxLength":2000},"departmentId":{"type":"string","format":"uuid"},"currency":{"type":"string","minLength":3,"maxLength":3},"preferredSupplierName":{"type":"string","maxLength":200},"deliverTo":{"type":"string","maxLength":500},"approverMembershipIds":{"description":"Replaces the approvers wholesale, in signing order — it is not a merge.\n\nTakes effect on the next submission. Editing a submitted request reopens\nit to `DRAFT` and supersedes its frozen route, so a requester cannot\nre-route a request somebody is still deciding.","type":"array","items":{"type":"string","format":"uuid"}},"expectedUpdatedAt":{"type":"string","description":"The `updatedAt` the edit was prepared against, exactly as it was read.\n\nWhen sent, the edit is refused with 409 `STALE_WRITE` — and nothing is\nwritten — if the requisition has been saved since. Omit it to keep the\nlast-write-wins behaviour.","example":"2026-09-28T09:14:03.120Z"}}},"ChangeRequisitionStatusDto":{"type":"object","properties":{"status":{"description":"SUBMITTED or CANCELLED. APPROVED and REJECTED are reached only through the approval routes.","enum":["DRAFT","SUBMITTED","CANCELLED"],"type":"string"}},"required":["status"]},"RequisitionLineActualDto":{"type":"object","properties":{"lineId":{"type":"string","format":"uuid"},"description":{"type":"string","example":"Transport for bracket and lock from yard to office"},"budgetLineId":{"type":"string","nullable":true,"format":"uuid"},"budgetLineDescription":{"type":"string","nullable":true,"example":"Office transport"},"costCentreCode":{"type":"string","nullable":true,"example":"CC-ADMIN"},"estimatedAmount":{"type":"string","example":"10000.0000","description":"The approved estimate, unchanged by recording an actual."},"actualAmount":{"type":"string","nullable":true,"example":"8500.0000","description":"NULL until recorded; `\"0.0000\"` is a recorded zero."},"varianceAmount":{"type":"string","nullable":true,"example":"-1500.0000","description":"`actualAmount - estimatedAmount`, signed: negative is under the estimate. NULL until recorded."},"recordedAt":{"type":"string","nullable":true,"format":"date-time"},"recordedByName":{"type":"string","nullable":true,"example":"Sharon Ayugi"},"procured":{"type":"boolean","description":"The line is on a live purchase order, so its supplier invoice carries its cost and an actual cannot be recorded here."}},"required":["lineId","description","budgetLineId","budgetLineDescription","costCentreCode","estimatedAmount","actualAmount","varianceAmount","recordedAt","recordedByName","procured"]},"RequisitionActualsDto":{"type":"object","properties":{"requisitionId":{"type":"string","format":"uuid"},"requisitionNumber":{"type":"string","example":"REQ-0041"},"currency":{"type":"string","nullable":true,"example":"UGX"},"estimatedTotal":{"type":"string","example":"10000.0000","description":"Every line’s estimate, the requisition’s approved total."},"actualTotal":{"type":"string","nullable":true,"example":"8500.0000","description":"The recorded lines’ actuals. NULL while no line is recorded."},"varianceTotal":{"type":"string","nullable":true,"example":"-1500.0000","description":"Summed over the recorded lines only — each against its own estimate — so a part-recorded requisition is not reported as under-spent. NULL while no line is recorded."},"recordedLineCount":{"type":"number","example":1},"lines":{"type":"array","items":{"$ref":"#/components/schemas/RequisitionLineActualDto"}}},"required":["requisitionId","requisitionNumber","currency","estimatedTotal","actualTotal","varianceTotal","recordedLineCount","lines"]},"RecordRequisitionLineActualDto":{"type":"object","properties":{"actualAmount":{"type":"string","nullable":true,"description":"What the line actually cost, as a decimal string — or `null` to clear a\nfigure recorded in error, returning the line to \"not recorded\". Zero is a\nreal answer and is kept distinct from `null`.","example":"8500.00"},"lineId":{"type":"string","description":"A line of the requisition in the path.","format":"uuid"}},"required":["actualAmount","lineId"]},"RecordRequisitionActualsDto":{"type":"object","properties":{"lines":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/RecordRequisitionLineActualDto"}}},"required":["lines"]},"RequisitionLinePaymentDto":{"type":"object","properties":{"paymentId":{"type":"string","format":"uuid"},"batchId":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"200000.0000"},"paidOn":{"type":"string","format":"date"},"method":{"enum":["MOBILE_MONEY","BANK","CASH"],"type":"string"},"reference":{"type":"string","nullable":true}},"required":["paymentId","batchId","amount","paidOn","method"]},"RequisitionLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","description":"Always the caller’s own organization."},"requisitionId":{"type":"string","format":"uuid","description":"Fixed at creation."},"projectId":{"type":"string","format":"uuid","description":"The requisition’s project. Derived, never client-supplied."},"budgetLineId":{"type":"string","nullable":true,"format":"uuid","description":"The budget line this request draws against, assigned by an approver. Null until then; every line of an `APPROVED` requisition has one."},"budgetLineDescription":{"type":"string","nullable":true,"description":"The budget line’s description, joined in for display."},"budgetLineAmount":{"type":"string","nullable":true,"example":"1250000000.00","description":"The amount that budget line authorizes, at 2 decimal places. Null when no budget line is assigned, **or when the caller does not hold `budget.view`** — a requisition is readable by people who are not entitled to the budget behind it."},"boqItemId":{"type":"string","nullable":true,"description":"The BOQ item behind the budget line, if any. Inherited through the budget line, not stored on this row.","format":"uuid"},"boqItemCode":{"type":"string","nullable":true,"example":"02.01.03","description":"The BOQ item’s code, joined in for display."},"costCentreId":{"type":"string","nullable":true,"format":"uuid"},"costCentreCode":{"type":"string","nullable":true,"example":"CC-CIVIL"},"requisitionTypeId":{"type":"string","format":"uuid"},"requisitionType":{"$ref":"#/components/schemas/RequisitionTypeSummaryDto"},"description":{"type":"string","example":"42 bags OPC 32.5N, delivered to gate 2"},"unit":{"type":"string","example":"bag"},"quantity":{"type":"string","example":"42.0000","description":"Decimal string with 4 decimal places, never a number."},"estimatedUnitCost":{"type":"string","example":"38500.0000","description":"The requester’s estimate of the unit price, not a price."},"estimatedAmount":{"type":"string","description":"Server-calculated `quantity × estimatedUnitCost`, exact to 4 decimal places. Read-only: sending it returns 400, and the database recomputes it on every change. An estimate, never a commitment.","example":"1617000.0000"},"sortOrder":{"type":"number","example":10},"route":{"enum":["STOCK","PURCHASE","PAY"],"type":"string","description":"Where this line goes after approval. Copied from its type when the requisition was submitted and fixed after that; STOCK for anything raised before routes existed."},"payeeName":{"type":"string","nullable":true},"payeeAccount":{"type":"string","nullable":true},"payeeMethod":{"nullable":true,"enum":["MOBILE_MONEY","BANK","CASH"],"type":"string"},"receivedConfirmedOn":{"type":"string","nullable":true,"format":"date","description":"PURCHASE lines: the day the requester confirmed it arrived or was done."},"receivedConfirmedAt":{"format":"date-time","type":"string","nullable":true},"receivedConfirmedByName":{"type":"string","nullable":true},"receivedConfirmedNote":{"type":"string","nullable":true},"payment":{"nullable":true,"description":"PAY lines: the live payment Finance recorded.","type":"object","allOf":[{"$ref":"#/components/schemas/RequisitionLinePaymentDto"}]},"ordered":{"type":"boolean","description":"On an ISSUED or CLOSED purchase order. A PURCHASE line can be confirmed received from then on."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","requisitionId","projectId","requisitionTypeId","requisitionType","description","unit","quantity","estimatedUnitCost","estimatedAmount","sortOrder","route","ordered","createdAt","updatedAt"]},"CreateRequisitionLineDto":{"type":"object","properties":{"budgetLineId":{"type":"string","description":"The budget line this request draws against. **Optional**, and normally\nomitted: the requester describes the need, and an approver assigns the\nbudget line at approval. Only a caller holding `budget.view` may set it\nhere (`403` otherwise) — somebody who cannot see the budget has no basis\nfor choosing a line of it.\n\nWhen given, the budget line must belong to the **same project** as this\nrequisition and to the caller's organization, and its budget must be\n`ACTIVE`. The first two are checked by the service for a friendly error and\nadditionally guaranteed by composite foreign keys, so a cross-project or\ncross-tenant request is unrepresentable rather than merely refused.","format":"uuid"},"requisitionTypeId":{"type":"string","description":"What kind of need this line is — Material, Labour, Transport. Must be an\n`ACTIVE` type of category `GENERAL`. **Optional**: omitted, the line takes\nthe requisition's own `requisitionTypeId`, which is what every line meant\nbefore types moved onto lines. A requisition's lines may carry different\ntypes; the requisition's own type is then the type of its first line.","format":"uuid"},"description":{"type":"string","description":"What is actually being asked for. Not a copy of the budget line's\ndescription: the budget authorizes \"concrete to substructure\", the request\nis for \"42 bags OPC 32.5N, delivered to gate 2\".","example":"42 bags OPC 32.5N, delivered to gate 2","maxLength":2000},"unit":{"type":"string","description":"Unit of measurement as free text — `bag`, `m3`, `tonne`, `day`. A `CASH`\nrequisition uses the currency code.","example":"bag","maxLength":16},"quantity":{"type":"string","description":"How much is needed, as a decimal **string**, never a JSON number — a number\nhas already passed through a double and lost exactness before the server\nsees it, so one is rejected with a 400.\n\nAt most 14 integer and 4 decimal digits, which is exactly what\n`numeric(18,4)` holds, so an oversized value is a 400 here rather than a\n500 from PostgreSQL. Zero is accepted on a draft being assembled; negative\nis not.","example":"42"},"estimatedUnitCost":{"type":"string","description":"The requester's **estimate** of the unit price, as a decimal string.\n\nAn estimate, and named so: the real price is discovered by procurement in a\nlater stage. This exists so a request carries a sense of scale an approver\ncan weigh against the budget.","example":"38500.00"},"sortOrder":{"type":"number","description":"Presentation position within the requisition. Defaults to `max + 10` among\nthe request's lines, leaving gaps to insert into.","minimum":0,"maximum":1000000000},"payeeName":{"type":"string","nullable":true,"example":"Shell Kampala Road","maxLength":200},"payeeAccount":{"type":"string","nullable":true,"description":"Phone number for mobile money, or bank account number.","example":"0772123456","maxLength":64},"payeeMethod":{"type":"string","nullable":true,"enum":["MOBILE_MONEY","BANK","CASH"]}},"required":["description","unit","quantity","estimatedUnitCost"]},"UpdateRequisitionLineDto":{"type":"object","properties":{"requisitionTypeId":{"type":"string","description":"Re-classifies the line. Same rule as on create: `ACTIVE` and `GENERAL`.","format":"uuid"},"description":{"type":"string","maxLength":2000},"unit":{"type":"string","maxLength":16},"quantity":{"type":"string"},"estimatedUnitCost":{"type":"string"},"sortOrder":{"type":"number","minimum":0,"maximum":1000000000},"payeeName":{"type":"string","nullable":true,"example":"Shell Kampala Road","maxLength":200},"payeeAccount":{"type":"string","nullable":true,"description":"Phone number for mobile money, or bank account number.","example":"0772123456","maxLength":64},"payeeMethod":{"type":"string","nullable":true,"enum":["MOBILE_MONEY","BANK","CASH"]}}},"RequisitionSummaryDto":{"type":"object","properties":{"requisitionCount":{"type":"number","description":"How many requisitions match, across every page.","example":19},"projectCount":{"type":"number","description":"How many distinct projects have a matching requisition.","example":4},"totalEstimatedAmount":{"type":"string","description":"Estimated value of every matching requisition, as a decimal string. Summed by the database from the lines, never in the client.","example":"509200000.0000"},"awaitingApprovalCount":{"type":"number","description":"How many are SUBMITTED and so awaiting somebody’s decision. Drafts are excluded — a draft has not been sent to anybody.","example":3},"awaitingApprovalAmount":{"type":"string","description":"Estimated value of those awaiting a decision.","example":"408400000.0000"}},"required":["requisitionCount","projectCount","totalEstimatedAmount","awaitingApprovalCount","awaitingApprovalAmount"]},"RequisitionRequesterDto":{"type":"object","properties":{"membershipId":{"type":"string","format":"uuid","description":"The requester’s organization membership — the value `requestedByMembershipId` takes on the register and its summary."},"name":{"type":"string","nullable":true,"example":"Grace Namutebi","description":"The requester’s name. Null when the user has no name on record, in which case show `email`."},"email":{"type":"string","nullable":true,"example":"grace@example.com"},"requisitionCount":{"type":"number","description":"How many requisitions they have raised, of every status, within the project filter.","example":7}},"required":["membershipId","name","email","requisitionCount"]},"CreateVehicleRequisitionDetailDto":{"type":"object","properties":{"vehicleRegistrationNumber":{"type":"string","maxLength":32},"driverName":{"type":"string","maxLength":200},"fromLocation":{"type":"string","maxLength":200},"toLocation":{"type":"string","maxLength":200},"distanceKm":{"type":"string","description":"Kilometres, as a decimal **string** — the same \"never a JSON number\"\ndiscipline every measured quantity in this API follows.","example":"184.50"},"vehicleEngineSizeCc":{"type":"number","description":"Optional: not every requester knows it, and it changes no calculation.","minimum":1,"maximum":50000},"litresRequired":{"type":"string","description":"Litres, as a decimal string.","example":"45.00"},"departureDate":{"type":"string","description":"Calendar date `YYYY-MM-DD`, not a timestamp — see `Requisition.needByDate`."},"returnDate":{"type":"string","description":"Must not be before `departureDate` — enforced by a database `CHECK`."},"passengerCount":{"type":"number","minimum":1,"maximum":100},"activityDescription":{"type":"string","maxLength":2000},"comments":{"type":"string","maxLength":2000}},"required":["vehicleRegistrationNumber","driverName","fromLocation","toLocation","distanceKm","litresRequired","departureDate","returnDate","passengerCount","activityDescription","comments"]},"CreateRequisitionDto":{"type":"object","properties":{"requisitionTypeId":{"type":"string","description":"What kind of need this is — an organization's own requisition type.\n\nIts `category` DOES change validation, unlike everything else about it:\na `VEHICLE`-category type requires `vehicleDetail` and forbids `lines`; a\n`GENERAL` one is the reverse. See `RequisitionsService.create`, which\nenforces this — a DTO-level `@ValidateIf` would need the type's category\nto already be known, which requires a lookup this DTO cannot perform.\n\n**Optional when the first line names its own.** Lines carry their own\ntype, so one requisition can hold Material, Labour and Transport lines\ntogether; the requisition's type is then its first line's. When given\nhere, lines that name none take it. Required for a VEHICLE requisition,\nand for one raised with no typed first line.","format":"uuid"},"bookSerialNumber":{"type":"string","description":"The paper requisition book's pre-printed S/NO, when transcribing one.\n\nOptional, and deliberately so: a requisition raised in the app has no\npaper original, and inventing a serial would corrupt the reference. Unique\nper organization where supplied — a serial identifies one physical page,\nso the same one twice is a transcription error.","example":"1822","maxLength":32},"purpose":{"type":"string","description":"Why the request exists, in the requester's words. Required: a request\nnobody can justify is one an approver cannot assess.","example":"Blinding to substructure, pour scheduled Friday","maxLength":1000},"needByDate":{"type":"string","description":"Calendar date, `YYYY-MM-DD`. Not a timestamp: a delivery is needed on a\nday, not at an instant. Optional — plenty of requests are simply \"as soon\nas possible\", and a fabricated deadline is worse than none.","example":"2026-03-01"},"notes":{"type":"string","maxLength":2000},"departmentId":{"type":"string","description":"The requesting department, if the organization tracks one. Descriptive\nonly, matching `RequisitionType` before its `category` existed — this\nchanges no lifecycle, no validation, no visibility. A deactivated\ndepartment is refused for a NEW reference the same way a deactivated\nrequisition type is, so choosing one afresh cannot silently point at a\nretired department; a request that already carries one keeps reading it.","format":"uuid"},"currency":{"type":"string","description":"ISO-4217 currency code, matching `boq.currency`/`budget.currency`.\nDeclarative only — nothing here converts between currencies.","example":"UGX","minLength":3,"maxLength":3},"preferredSupplierName":{"type":"string","description":"A named supplier, informally — free text, not a link to the Supplier\nregister. Turns a competitive route into a single-source case at the\norganization form's discretion; nothing here enforces that policy.","maxLength":200},"deliverTo":{"type":"string","description":"Where on site or in the organization the order should be delivered.","maxLength":500},"approverMembershipIds":{"description":"The memberships that must approve this, **in signing order**.\n\nOptional here and required at SUBMISSION, which is deliberate: a draft may\nlegitimately be saved before the requester has decided who should sign it,\nbut nothing reaches an approval queue without somebody named. That rule\nlives in `ApprovalsService.openFor`, because it is a statement about\nrouting rather than about this payload.\n\nOrder is meaningful and preserved as sent — the first named approves first.\n\nEvery id is checked at submission against live memberships: each must be\nactive, hold `approval.decide`, appear once, and not be the requester.\nA requester cannot authorize their own spending, and naming themselves here\nis refused rather than silently dropped.","type":"array","items":{"type":"string","format":"uuid"}},"vehicleDetail":{"description":"Trip particulars for a `VEHICLE`-category requisition, in place of lines.\n\nRequired when the resolved requisition type's `category` is `VEHICLE`\nand forbidden otherwise — enforced by `RequisitionsService.create`, not\nby this DTO, because the rule depends on a row this DTO has not read.","allOf":[{"$ref":"#/components/schemas/CreateVehicleRequisitionDetailDto"}]},"lines":{"description":"Lines to create with the requisition, committed in the **same transaction**\nas the header and its generated number.\n\nOptional: a requisition may be raised empty and filled in while it is still\na draft. When supplied, either everything commits or nothing does — a\nhalf-built request that looks complete is the hazard the transaction exists\nto prevent.\n\nMust be ABSENT for a `VEHICLE`-category requisition — see `vehicleDetail`.","type":"array","items":{"$ref":"#/components/schemas/CreateRequisitionLineDto"}}},"required":["purpose"]},"ApprovalPolicyStepDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"policyId":{"type":"string","format":"uuid"},"stepNumber":{"type":"number","example":1},"roleId":{"type":"string","format":"uuid"},"roleName":{"type":"string","nullable":true,"description":"The role’s current name, joined in for display. Null if the role has since been deleted.","example":"Site Manager"},"minAmount":{"type":"string","description":"Inclusive lower bound, as a decimal string.","example":"0.00"},"maxAmount":{"type":"string","nullable":true,"description":"Inclusive upper bound, or null for no ceiling.","example":"5000000.00"}},"required":["id","policyId","stepNumber","roleId","minAmount"]},"ApprovalPolicyDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Standard thresholds"},"description":{"type":"string","nullable":true},"status":{"enum":["DRAFT","ACTIVE","CLOSED"],"type":"string"},"stepCount":{"type":"number","description":"How many steps this policy defines.","example":2},"steps":{"description":"The ladder, in step order. Present on a single-policy read, omitted from listings.","type":"array","items":{"$ref":"#/components/schemas/ApprovalPolicyStepDto"}},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","name","status","stepCount","createdAt","updatedAt"]},"CreateApprovalPolicyStepDto":{"type":"object","properties":{"stepNumber":{"type":"number","description":"Position in the ladder, from 1. Steps are collected in this order, so step\n2 becomes actionable only once step 1 has approved.","example":1,"minimum":1,"maximum":100},"roleId":{"type":"string","description":"The role whose holders may approve at this step.\n\nA role, never a person: naming an individual would break the policy every\ntime somebody changed jobs. Who holds the role is resolved at submission\nand frozen into the request's own copy of the route.","example":"6f1c1a2e-1f4b-4c8a-9a1e-2b7d3f5a9c11","format":"uuid"},"minAmount":{"type":"string","description":"Inclusive lower bound of the value range this step covers, as a decimal\nstring. Defaults to `\"0.00\"`.","example":"0.00"},"maxAmount":{"type":"string","description":"Inclusive upper bound, or omitted for no ceiling.\n\nExactly one step in a policy should omit it — the authority of last\nresort. Activation refuses a policy whose bands leave large requests\nuncovered.","example":"5000000.00"}},"required":["stepNumber","roleId"]},"CreateApprovalPolicyDto":{"type":"object","properties":{"name":{"type":"string","description":"What the firm calls this set of rules.","example":"Standard thresholds","minLength":1,"maxLength":200},"description":{"type":"string","example":"Approval ladder adopted at the 2026 board meeting","maxLength":1000},"steps":{"description":"The ladder itself, created atomically with the policy.\n\nOptional so a policy can be assembled step by step, but a policy with no\nsteps cannot be activated — it would authorize nothing.","type":"array","items":{"$ref":"#/components/schemas/CreateApprovalPolicyStepDto"}}},"required":["name"]},"UpdateApprovalPolicyDto":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":1000}}},"ChangeApprovalPolicyStatusDto":{"type":"object","properties":{"status":{"type":"string","description":"The state to move to. `DRAFT → ACTIVE | CLOSED`, `ACTIVE → CLOSED`;\n`CLOSED` is terminal.","example":"ACTIVE","enum":["DRAFT","ACTIVE","CLOSED"]}},"required":["status"]},"EligibleApproverDto":{"type":"object","properties":{"membershipId":{"type":"string","format":"uuid","description":"The MEMBERSHIP id, not the user id — what `approverMembershipIds` on a requisition expects."},"fullName":{"type":"string","example":"Sarah Nakato"},"roleNames":{"description":"The roles they hold, for telling apart two people with the same name.","example":["Project Manager"],"type":"array","items":{"type":"string"}}},"required":["membershipId","fullName","roleNames"]},"ApprovalStepEditDto":{"type":"object","properties":{"editedAt":{"format":"date-time","type":"string"},"editedByName":{"type":"string","nullable":true,"example":"Sharon Ayugi"},"totalBefore":{"type":"string","nullable":true,"example":"13000.0000"},"totalAfter":{"type":"string","nullable":true,"example":"15000.0000"}},"required":["editedAt"]},"ApprovalStepDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"stepNumber":{"type":"number","example":1},"roleId":{"type":"string","nullable":true,"format":"uuid","description":"The role required at this step, as it stood when the requisition was submitted. NULL when the step names an individual instead — a step carries a role or an approver, never both."},"roleNameAtSubmission":{"type":"string","nullable":true,"description":"What that role was called at submission. Stored, so the record still reads correctly after a rename or deletion.","example":"Site Manager"},"approverMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"The individual required at this step — named by the requester when the requisition was raised. NULL when the step is routed by role instead."},"approverNameAtSubmission":{"type":"string","nullable":true,"description":"What that person was called at submission. Stored for the same reason as the role name: the record must still read correctly after they leave.","example":"Sarah Nakato"},"minAmount":{"type":"string","example":"0.00"},"maxAmount":{"type":"string","nullable":true,"example":"5000000.00"},"decision":{"nullable":true,"enum":["APPROVED","REJECTED"],"type":"string","description":"Null while this step is still awaiting a decision."},"decidedAt":{"format":"date-time","type":"string","nullable":true},"decidedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"decidedByName":{"type":"string","nullable":true,"example":"Amina Nakato"},"decidedByOverride":{"type":"boolean","description":"True when the decision was an administrator’s override rejection (`approval.override`) rather than this step’s approver’s own. `decidedByName` is then the administrator."},"comment":{"type":"string","nullable":true},"inPlaceEdits":{"description":"Edits this step’s approver made in place while it was their turn, oldest first. Decisions at earlier steps were taken on the figures before these edits.","type":"array","items":{"$ref":"#/components/schemas/ApprovalStepEditDto"}}},"required":["id","stepNumber","minAmount","decidedByOverride","inPlaceEdits"]},"ApprovalDecisionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"stepNumber":{"type":"number","example":1},"decision":{"enum":["APPROVED","REJECTED"],"type":"string"},"approverMembershipId":{"type":"string","format":"uuid"},"approverName":{"type":"string","nullable":true,"example":"Amina Nakato"},"approverEmail":{"type":"string","nullable":true},"comment":{"type":"string","nullable":true},"totalAmountAtDecision":{"type":"string","description":"The requisition’s total when this decision was taken, as a decimal string.","example":"1617000.0000"},"budgetRemainingAtDecision":{"type":"string","nullable":true,"description":"What was left of the budget drawn against, at decision time. NEGATIVE when the request exceeded its authorization — approving over budget is permitted, and this is what records that the approver could see the overrun.","example":"-500000.0000"},"decidedAt":{"format":"date-time","type":"string"},"isOverride":{"type":"boolean","description":"True for an administrator’s override rejection (`approval.override`): taken by somebody who was not this step’s approver. Always a rejection."}},"required":["id","stepNumber","decision","approverMembershipId","totalAmountAtDecision","decidedAt","isOverride"]},"ApprovalDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"requisitionId":{"type":"string","format":"uuid"},"policyId":{"type":"string","nullable":true,"format":"uuid","description":"The policy this route was taken from, for provenance. Null when the organization had no active policy at submission. The route actually enforced is the frozen copy in `steps`, never this policy."},"status":{"enum":["PENDING","APPROVED","REJECTED","SUPERSEDED"],"type":"string"},"currentStep":{"type":"number","description":"Which step is awaiting a decision.","example":1},"requiredStepCount":{"type":"number","description":"How many approvals this request must collect. Zero when no policy step applied, in which case the request was authorized on submission.","example":2},"totalAmountAtSubmission":{"type":"string","description":"The requisition’s total when it entered approval, as a decimal string.","example":"1617000.0000"},"requestedByMembershipId":{"type":"string","format":"uuid"},"decidedAt":{"format":"date-time","type":"string","nullable":true},"steps":{"description":"The frozen route, in step order, each carrying its decision.","type":"array","items":{"$ref":"#/components/schemas/ApprovalStepDto"}},"decisions":{"description":"Every decision taken, oldest first. Never edited or removed.","type":"array","items":{"$ref":"#/components/schemas/ApprovalDecisionDto"}},"requisitionNumber":{"type":"string","description":"The requisition’s number. Inbox listings only.","example":"REQ-0042"},"purpose":{"type":"string","description":"Why the requisition was raised. Inbox listings only."},"currency":{"type":"string","description":"The requisition’s currency, so `totalAmountAtSubmission` can be read. Inbox listings only.","example":"UGX"},"needByDate":{"type":"string","nullable":true,"description":"When the request is needed, or null where it carries no deadline. Inbox listings only.","example":"2026-10-15"},"projectName":{"type":"string","description":"Inbox listings only."},"projectCode":{"type":"string","description":"Inbox listings only."},"requesterName":{"type":"string","nullable":true,"description":"Who raised the requisition. Null where that membership no longer resolves to a user. Inbox listings only."},"currentApproverName":{"type":"string","nullable":true,"description":"Who the current step names, where it names a person. Null when the step routes by role. Inbox listings only."},"currentRoleName":{"type":"string","nullable":true,"description":"The role the current step names, where it routes by role. Null when the step names a person. Inbox listings only."},"totalEstimatedAmount":{"type":"string","description":"The requisition’s total now, as a decimal string. Differs from `totalAmountAtSubmission` once an approver has corrected the request in place. Inbox listings only.","example":"1617000.0000"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","requisitionId","status","currentStep","requiredStepCount","totalAmountAtSubmission","requestedByMembershipId","createdAt","updatedAt"]},"ApprovalBudgetLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"budgetId":{"type":"string","format":"uuid"},"description":{"type":"string","example":"Concrete to substructure"},"amount":{"type":"string","example":"1250000000.00","description":"The original authorized amount, at 2 decimal places."},"boqItemCode":{"type":"string","nullable":true,"example":"02.01.03"},"costCentreCode":{"type":"string","nullable":true,"example":"CC-CIVIL"},"sortOrder":{"type":"number","example":10},"exposure":{"description":"Revised amount, what SUBMITTED and APPROVED requisitions have requested against it, and the remainder — which may be negative.","allOf":[{"$ref":"#/components/schemas/BudgetLineExposureDto"}]}},"required":["id","budgetId","description","amount","sortOrder","exposure"]},"LineAssignmentDto":{"type":"object","properties":{"lineId":{"type":"string","description":"A line of the requisition being approved.","format":"uuid"},"budgetLineId":{"type":"string","description":"A budget line of an `ACTIVE` budget on the requisition's project.","format":"uuid"}},"required":["lineId","budgetLineId"]},"ApproveRequisitionDto":{"type":"object","properties":{"lineAssignments":{"description":"Budget lines to assign or change, one entry per line. Lines left out keep\nwhat they have. Any approver may assign or change a line at their step;\nthe **final** approval is refused while any line is still unassigned.","type":"array","items":{"$ref":"#/components/schemas/LineAssignmentDto"}},"comment":{"type":"string","description":"Why. Required when rejecting — a refusal nobody can explain leaves the\nrequester unable to tell what to change. Optional when approving, since the\nrequest itself is the case for it.","example":"\"Approved — within the quarter\"s materials allowance.\"","maxLength":2000}}},"DecideApprovalDto":{"type":"object","properties":{"comment":{"type":"string","description":"Why. Required when rejecting — a refusal nobody can explain leaves the\nrequester unable to tell what to change. Optional when approving, since the\nrequest itself is the case for it.","example":"\"Approved — within the quarter\"s materials allowance.\"","maxLength":2000}}},"AuditEventDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"enum":["boq_management","budget_management","requisitions","procurement","inventory","access_control","project_lifecycle"],"type":"string"},"action":{"enum":["boq_ratified","boq_imported","boq_item_deleted","budget_transferred","requisition_submitted","requisition_approved","requisition_rejected","requisition_cancelled","requisition_budget_line_assigned","requisition_updated","requisition_actual_recorded","purchase_order_issued","purchase_order_cancelled","purchase_order_closed","goods_receipt_posted","material_issue_posted","material_issue_cancelled","stock_transfer_dispatched","stock_transfer_received","stock_transfer_cancelled","material_return_posted","material_return_cancelled","supplier_return_posted","supplier_return_cancelled","supplier_invoice_submitted","supplier_invoice_approved","supplier_invoice_held","supplier_invoice_released","supplier_invoice_cancelled","supplier_payment_posted","supplier_payment_voided","rfq_issued","rfq_awarded","rfq_cancelled","subcontract_activated","subcontract_variation_approved","subcontract_valuation_certified","subcontract_practically_complete","subcontract_final_account_closed","subcontract_terminated","inventory_adjustment_approved","inventory_adjustment_rejected","stock_count_posted","project_member_added","project_member_status_changed","stock_count_sent_to_finance","stock_count_returned_for_recount","project_reopen_requested","project_reopen_approved","project_reopen_rejected"],"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"reference":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"actorMembershipId":{"type":"string","nullable":true,"format":"uuid"},"actorName":{"type":"string","nullable":true}},"required":["id","category","action","title","description","reference","occurredAt"]},"CreateSupplierDto":{"type":"object","properties":{"supplierCode":{"type":"string","description":"Short identifier, unique within the organization. Upper-cased on input, so\n`acme` and `ACME` cannot become two payees.","example":"ACME-001","maxLength":32},"name":{"type":"string","description":"Legal or trading name, as it should appear on a purchase order.","example":"Acme Building Supplies Ltd","maxLength":200},"supplierType":{"type":"string","description":"What the firm mostly engages them for. Defaults to MATERIALS.","enum":["MATERIALS","SERVICES","SUBCONTRACTOR","PLANT_HIRE","CONSULTANT"]},"taxRegistrationNumber":{"type":"string","description":"Tax registration number (TIN). Spaces are removed and letters upper-cased,\nso `1000 123 456` and `1000123456` are recognised as one supplier — a\nsecond supplier with the same number returns 409.","example":"1000123456","maxLength":32},"vatRegistered":{"type":"boolean"},"paymentTermsDays":{"type":"number","description":"Days after the invoice date that payment falls due. Omit when no terms\nhave been agreed — that is not the same as 0, due on the day.","example":30,"minimum":0,"maximum":365},"defaultCurrency":{"type":"string","description":"ISO 4217. Declarative only — nothing converts currencies."},"website":{"type":"string","maxLength":200,"format":"uri"},"contactName":{"type":"string","maxLength":200},"contactEmail":{"type":"string","description":"Validated as an address, but nothing in D.8 sends to it — supplier\nnotification is deferred. Recorded so a buyer can reach them by their own\nmeans, which is how orders are actually placed today.","maxLength":320,"format":"email"},"contactPhone":{"type":"string","description":"Free text: international formats, extensions and multiple numbers vary too much to constrain.","maxLength":40},"address":{"type":"string","maxLength":500},"postalAddress":{"type":"string","maxLength":500},"notes":{"type":"string","maxLength":500}},"required":["supplierCode","name"]},"SupplierDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","description":"Always the caller’s own organization."},"supplierCode":{"type":"string","example":"ACME-001","description":"Unique within the organization. Upper-cased, and immutable once set."},"name":{"type":"string","example":"Acme Building Supplies Ltd"},"supplierType":{"enum":["MATERIALS","SERVICES","SUBCONTRACTOR","PLANT_HIRE","CONSULTANT"],"type":"string"},"taxRegistrationNumber":{"type":"string","nullable":true,"example":"1000123456"},"vatRegistered":{"type":"boolean"},"paymentTermsDays":{"type":"number","nullable":true,"description":"Days after the invoice date. Null when no terms are agreed."},"defaultCurrency":{"type":"string","nullable":true,"example":"UGX"},"website":{"type":"string","nullable":true},"contactName":{"type":"string","nullable":true},"contactEmail":{"type":"string","nullable":true},"contactPhone":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"postalAddress":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string","description":"INACTIVE bars new purchase orders. Orders already issued are unaffected."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","supplierCode","name","supplierType","vatRegistered","status","createdAt","updatedAt"]},"UpdateSupplierDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"supplierType":{"type":"string","description":"What the firm mostly engages them for. Defaults to MATERIALS.","enum":["MATERIALS","SERVICES","SUBCONTRACTOR","PLANT_HIRE","CONSULTANT"]},"taxRegistrationNumber":{"type":"string","description":"Tax registration number (TIN). Spaces are removed and letters upper-cased,\nso `1000 123 456` and `1000123456` are recognised as one supplier — a\nsecond supplier with the same number returns 409.","example":"1000123456","maxLength":32},"vatRegistered":{"type":"boolean"},"paymentTermsDays":{"type":"number","description":"Days after the invoice date that payment falls due. Omit when no terms\nhave been agreed — that is not the same as 0, due on the day.","example":30,"minimum":0,"maximum":365},"defaultCurrency":{"type":"string","description":"ISO 4217. Declarative only — nothing converts currencies."},"website":{"type":"string","maxLength":200,"format":"uri"},"contactName":{"type":"string","maxLength":200},"contactEmail":{"type":"string","maxLength":320,"format":"email"},"contactPhone":{"type":"string","maxLength":40},"address":{"type":"string","maxLength":500},"postalAddress":{"type":"string","maxLength":500},"notes":{"type":"string","maxLength":500},"status":{"type":"string","description":"`INACTIVE` bars the supplier from **new** purchase orders, checked both\nwhen an order names them and when one is issued.\n\nOrders already issued are untouched: retiring a supplier must not rewrite\nhistory. This is the retirement path — there is no delete, because a\nsupplier named on an order must stay readable for that order to make sense.","enum":["ACTIVE","INACTIVE"]}}},"SupplierContactDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"supplierId":{"type":"string","format":"uuid"},"name":{"type":"string"},"role":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","supplierId","name","createdAt","updatedAt"]},"CreateSupplierContactDto":{"type":"object","properties":{"name":{"type":"string","example":"Grace Namutebi","maxLength":200},"role":{"type":"string","description":"What they do there.","example":"Accounts","maxLength":100},"email":{"type":"string","description":"Recorded only. Nothing sends to it.","maxLength":320,"format":"email"},"phone":{"type":"string","maxLength":40},"notes":{"type":"string","maxLength":500}},"required":["name"]},"UpdateSupplierContactDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"role":{"type":"string","maxLength":100},"email":{"type":"string","maxLength":320,"format":"email"},"phone":{"type":"string","maxLength":40},"notes":{"type":"string","maxLength":500}}},"SupplierBankAccountDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"supplierId":{"type":"string","format":"uuid"},"bankName":{"type":"string"},"branchName":{"type":"string","nullable":true},"accountName":{"type":"string"},"accountNumber":{"type":"string","description":"In full. Only served behind `supplier.view_bank_details`, never on the supplier itself."},"swiftCode":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"status":{"enum":["PENDING_VERIFICATION","VERIFIED","RETIRED"],"type":"string","description":"Only VERIFIED may be paid into. RETIRED is terminal; a reinstated account is recorded afresh."},"isDefault":{"type":"boolean"},"recordedByMembershipId":{"type":"string","format":"uuid"},"verifiedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"verifiedAt":{"format":"date-time","type":"string","nullable":true},"retiredByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"retiredAt":{"format":"date-time","type":"string","nullable":true},"retirementReason":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"When it was recorded."},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","supplierId","bankName","accountName","accountNumber","status","isDefault","recordedByMembershipId","createdAt","updatedAt"]},"CreateSupplierBankAccountDto":{"type":"object","properties":{"bankName":{"type":"string","example":"Stanbic Bank Uganda","maxLength":200},"branchName":{"type":"string","example":"Kampala Road","maxLength":200},"accountName":{"type":"string","description":"The name the account is held in. Should match the supplier's — a mismatch\nis exactly what the verifier is there to question.","example":"Acme Building Supplies Ltd","maxLength":200},"accountNumber":{"type":"string","description":"Spaces are removed; otherwise stored as entered, since formats vary too\nmuch by bank to validate further.","example":"9030012345678","maxLength":64},"swiftCode":{"type":"string","description":"SWIFT/BIC: 8 or 11 characters.","example":"SBICUGKX","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$"},"currency":{"type":"string","description":"ISO 4217, when the account is held in a specific currency."}},"required":["bankName","accountName","accountNumber"]},"VerifySupplierBankAccountDto":{"type":"object","properties":{"makeDefault":{"type":"boolean"}}},"RetireSupplierBankAccountDto":{"type":"object","properties":{"reason":{"type":"string","example":"Supplier closed this account and confirmed a replacement by phone","maxLength":500}},"required":["reason"]},"CreatePurchaseOrderLineDto":{"type":"object","properties":{"requisitionLineId":{"type":"string","description":"The requisition line this procures. **Required**, and must belong to the\norder's own requisition — proved by composite foreign key, not by service\ncode a bulk import could bypass.\n\nOne order may not bill the same requisition line twice: a second line\nagainst the same need returns 409.","format":"uuid"},"stockItemId":{"type":"string","description":"The catalogue item being bought — what makes this line's deliveries become\nstock (D.10).\n\nOptional, and omitting it is a meaningful answer: a line for consultancy,\nlabour or plant hire names no stock item, receives normally, and produces no\nstock movement. Whether a *named* item actually moves stock is then\n`stockItem.isStockControlled`.\n\nSet it here rather than at receiving so that two deliveries against this\nline cannot disagree about what arrived.","format":"uuid"},"description":{"type":"string","description":"What is being ordered, in the buyer's words. Defaults to the requisition\nline's description when omitted.\n\nEditable rather than copied verbatim because the two serve different\nreaders: the requisition says \"42 bags OPC for the substructure\", while the\norder must say what the supplier will recognise on their own price list.","example":"OPC 32.5N cement, 50kg bags — delivered to gate 2","maxLength":2000},"unit":{"type":"string","description":"Defaults to the requisition line's unit when omitted.","maxLength":16},"quantity":{"type":"string","description":"How much is being ordered, as a decimal **string**, never a JSON number — a\nnumber has already passed through a double and lost exactness before the\nserver sees it, so one is rejected with a 400.\n\nAt most 14 integer and 4 decimal digits, which is exactly what\n`numeric(18,4)` holds. **Zero is refused**, unlike on a requisition line: a\nplaceholder is legitimate on a draft request, but committing to buy nothing\nis a line that should not be on the order.\n\nCumulative *issued* quantity across every order against one requisition\nline may not exceed what was requested. That is checked at issue, not here\n— a draft may exceed it freely, and reads show `orderedQuantity` beside\n`requestedQuantity` so the overrun is visible before an issue is attempted.","example":"42"},"unitPrice":{"type":"string","description":"The **agreed** price per unit, as a decimal string. Defaults to the\nrequisition line's estimate when omitted — purely as a starting point a\nbuyer overwrites.\n\nMoney, at two decimal places, and the scale is the point: the requisition's\n`estimatedUnitCost` is `numeric(18,4)` because it is an estimate of a rate,\nwhile this is money agreed with a named supplier. Zero is legitimate — free\nissue, samples and supplier-borne replacements are ordered at nil and must\nstill appear on the order.","example":"38500.00"},"sortOrder":{"type":"number","description":"Presentation position within the order. Defaults to `max + 10` among the\norder's lines, leaving gaps to insert into.","minimum":0,"maximum":1000000}},"required":["requisitionLineId","quantity"]},"CreatePurchaseOrderDto":{"type":"object","properties":{"requisitionId":{"type":"string","description":"The approved requisition this order procures. **Required.**\n\nMust be `APPROVED` — an order against an unapproved request would be a\ncommitment nobody authorized. The project is taken from it rather than\naccepted separately, so an order cannot claim a project its requisition\ndoes not belong to.","example":"7f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8","format":"uuid"},"supplierId":{"type":"string","description":"Who the order is placed with. Must be `ACTIVE` at creation and again at\nissue — a supplier retired in between must not be bound at the moment the\nfirm commits.","format":"uuid"},"currency":{"type":"string","description":"ISO 4217 code. **Declarative only** — nothing in the system converts\nbetween currencies, so an order in a currency its budget is not\ndenominated in will report a committed figure that does not mean what it\nappears to.","example":"UGX"},"orderDate":{"type":"string","description":"Calendar date, `YYYY-MM-DD`. The date the order is dated, which need not\nbe the day it was keyed in.","example":"2026-03-01"},"expectedDeliveryDate":{"type":"string","description":"Calendar date, `YYYY-MM-DD`. Not enforced against anything; D.9 will compare receipts to it."},"notes":{"type":"string","description":"Delivery instructions, terms, or anything else the buyer wants on the order.","maxLength":2000},"lines":{"description":"Lines to create with the order, committed in the **same transaction** as\nthe header and its generated number.\n\nOptional: an order may be raised empty and filled in while it is still a\ndraft. When supplied, either everything commits or nothing does.","type":"array","items":{"$ref":"#/components/schemas/CreatePurchaseOrderLineDto"}}},"required":["requisitionId","supplierId"]},"PurchaseOrderDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","description":"Always the caller’s own organization."},"projectId":{"type":"string","format":"uuid","description":"Taken from the requisition, never supplied separately."},"requisitionId":{"type":"string","format":"uuid","description":"The approved requisition this order procures."},"requisitionNumber":{"type":"string","nullable":true,"example":"REQ-0001","description":"The requisition’s number, joined in for display."},"supplierId":{"type":"string","format":"uuid"},"rfqId":{"type":"string","nullable":true,"format":"uuid","description":"The request for quotation this order was awarded from; null for an order raised directly."},"supplierCode":{"type":"string","nullable":true,"example":"ACME-001","description":"The supplier’s code, joined in for display."},"supplierName":{"type":"string","nullable":true,"example":"Acme Building Supplies Ltd","description":"The supplier’s name, joined in for display."},"purchaseOrderNumber":{"type":"string","example":"PO-0001","description":"Server-generated, sequential within the project, immutable once set."},"status":{"enum":["DRAFT","ISSUED","CANCELLED","CLOSED"],"type":"string","description":"Changed only through the issue, cancel and close routes. Everything but DRAFT is locked against every edit."},"currency":{"type":"string","nullable":true,"example":"UGX","description":"ISO 4217. Declarative only — nothing converts currencies."},"orderDate":{"type":"string","nullable":true,"example":"2026-03-01","description":"Calendar date, `YYYY-MM-DD`."},"expectedDeliveryDate":{"type":"string","nullable":true,"example":"2026-03-14","description":"Calendar date, `YYYY-MM-DD`."},"notes":{"type":"string","nullable":true},"raisedByMembershipId":{"type":"string","format":"uuid","description":"The membership that raised the order. Derived from the authenticated session, never client-supplied."},"raisedByName":{"type":"string","nullable":true,"description":"The raiser’s name, joined in for display."},"issuedByMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"The membership that issued the order, and therefore committed the organization. Null until issue."},"issuedByName":{"type":"string","nullable":true,"description":"The issuer’s name, joined in for display."},"issuedAt":{"type":"string","nullable":true,"format":"date-time","description":"When the order was issued. Never cleared."},"budgetRemainingAtIssue":{"type":"string","nullable":true,"description":"What remained of the budget across this order’s lines at the moment it was issued, read live inside the issuing transaction. A record, not a control: an over-budget order is permitted, and a negative figure here is exactly the case worth recording.","example":"-450000.0000"},"cancelledAt":{"type":"string","nullable":true,"format":"date-time"},"cancellationReason":{"type":"string","nullable":true},"closedAt":{"type":"string","nullable":true,"format":"date-time"},"totalAmount":{"type":"string","description":"Server-calculated SUM of line amounts, exact to 4 decimal places. Read-only and derived. A commitment once issued — never a cost.","example":"3187500.0000"},"lineCount":{"type":"number","example":4,"description":"Number of lines on this order."},"projectName":{"type":"string","nullable":true,"example":"Kampala Ring Road","description":"The project’s name, joined in for display. Order numbers restart in every project, so a cross-project register needs this to identify a row."},"projectCode":{"type":"string","nullable":true,"example":"KRR-001","description":"The project’s code, joined in for display."},"receiptStatus":{"enum":["NOT_RECEIVED","PARTIALLY_RECEIVED","FULLY_RECEIVED"],"type":"string","example":"PARTIALLY_RECEIVED","description":"How much of the order has arrived, derived on every read from POSTED goods receipts. Orthogonal to `status`: a CLOSED order can be PARTIALLY_RECEIVED. Per-line detail is on `/purchase-orders/:id/receiving`."},"receivable":{"type":"boolean","example":true,"description":"Whether goods can be received against this order at all — the requisition type’s `isReceivable`. A cash order is settled, not delivered, and `POST /goods-receipts` refuses it."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","requisitionId","supplierId","purchaseOrderNumber","status","raisedByMembershipId","totalAmount","lineCount","receiptStatus","receivable","createdAt","updatedAt"]},"UpdatePurchaseOrderDto":{"type":"object","properties":{"supplierId":{"type":"string","description":"Changing the supplier on a draft is legitimate — that is what a draft is for.","format":"uuid"},"currency":{"type":"string"},"orderDate":{"type":"string"},"expectedDeliveryDate":{"type":"string"},"notes":{"type":"string","maxLength":2000},"expectedUpdatedAt":{"type":"string","description":"The `updatedAt` the edit was prepared against, exactly as it was read.\n\nWhen sent, the edit is refused with 409 `STALE_WRITE` — and nothing is\nwritten — if the order has been saved since. Omit it to keep the\nlast-write-wins behaviour.","example":"2026-09-28T09:14:03.120Z"}}},"CancelPurchaseOrderDto":{"type":"object","properties":{"reason":{"type":"string","description":"Why the order is being cancelled.","example":"Supplier cannot meet the delivery date; re-ordering from Bamburi","maxLength":1000}},"required":["reason"]},"PurchaseOrderLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"stockItemId":{"type":"string","nullable":true,"description":"The catalogue item this line buys, or `null` for a line that never becomes\nstock. See `CreatePurchaseOrderLineDto.stockItemId`.","format":"uuid"},"requisitionId":{"type":"string","format":"uuid"},"requisitionLineId":{"type":"string","format":"uuid","description":"The requisition line this procures."},"requisitionLineDescription":{"type":"string","nullable":true,"description":"The requisition line’s own description, joined in for display."},"description":{"type":"string","example":"OPC 32.5N cement, 50kg bags — delivered to gate 2"},"unit":{"type":"string","example":"bag"},"quantity":{"type":"string","example":"42.0000","description":"Ordered quantity, exact to 4 decimal places."},"unitPrice":{"type":"string","example":"38500.00","description":"The agreed price per unit, exact to 2 decimal places. Money — not the requisition’s estimate."},"lineAmount":{"type":"string","example":"1617000.0000","description":"quantity × unitPrice, computed by PostgreSQL as a stored generated column. Read-only: no code path can store a total that contradicts its own operands. Held at 4 decimal places so a 4dp quantity times a 2dp price is not silently rounded."},"sortOrder":{"type":"number","example":10},"requestedQuantity":{"type":"string","nullable":true,"description":"What the requisition line asked for. The approved quantity: approval is all-or-nothing, so the requested figure is what was authorized.","example":"42.0000"},"orderedQuantity":{"type":"string","nullable":true,"example":"30.0000","description":"Quantity already committed on other ISSUED or CLOSED orders against this requisition line. Issuing this order is refused if the cumulative total would exceed requestedQuantity."},"estimatedUnitCost":{"type":"string","nullable":true,"description":"The requisition line’s estimate, for comparison with unitPrice."},"budgetLineId":{"type":"string","nullable":true,"format":"uuid"},"budgetLineDescription":{"type":"string","nullable":true},"boqItemId":{"type":"string","nullable":true,"format":"uuid"},"boqItemCode":{"type":"string","nullable":true},"costCentreId":{"type":"string","nullable":true,"format":"uuid"},"costCentreCode":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","purchaseOrderId","projectId","stockItemId","requisitionId","requisitionLineId","description","unit","quantity","unitPrice","lineAmount","sortOrder","createdAt","updatedAt"]},"UpdatePurchaseOrderLineDto":{"type":"object","properties":{"stockItemId":{"type":"string","description":"Re-point this line at a different catalogue item, or name one that was\nmissed. Editable only while the order is DRAFT, like every other field here\n— once the order is issued the line is a commitment, and by the time a\nreceipt is posted the item has already decided what entered the ledger.","format":"uuid"},"description":{"type":"string","maxLength":2000},"unit":{"type":"string","maxLength":16},"quantity":{"type":"string"},"unitPrice":{"type":"string"},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}}},"RequisitionProcurementDto":{"type":"object","properties":{"requisitionLineId":{"type":"string","format":"uuid"},"description":{"type":"string","example":"42 bags OPC 32.5N for the substructure"},"requestedQuantity":{"type":"string","example":"100.0000","description":"What the requisition asked for — and therefore what was approved, since approval is all-or-nothing on the whole requisition."},"orderedQuantity":{"type":"string","example":"60.0000","description":"Committed on ISSUED or CLOSED purchase orders. Drafts and cancelled orders are excluded: a draft commits nothing, and a cancelled order buys nothing."},"remainingQuantity":{"type":"string","example":"40.0000","description":"requestedQuantity − orderedQuantity. Can be optimistic while other buyers hold drafts, since only issuing consumes quantity; issue re-checks under a row lock and may still refuse."}},"required":["requisitionLineId","description","requestedQuantity","orderedQuantity","remainingQuantity"]},"PurchaseOrderStatusCountsDto":{"type":"object","properties":{"DRAFT":{"type":"number"},"ISSUED":{"type":"number"},"CANCELLED":{"type":"number"},"CLOSED":{"type":"number"}},"required":["DRAFT","ISSUED","CANCELLED","CLOSED"]},"ProcurementCurrencyTotalDto":{"type":"object","properties":{"currency":{"type":"string","nullable":true,"example":"UGX","description":"ISO 4217 code, or `null` for records that declare no currency."},"amount":{"type":"string","example":"1530000000.0000","description":"Summed by the database, as a decimal string."},"count":{"type":"number","description":"Records contributing to this total."}},"required":["amount","count"]},"PurchaseOrderReceiptCountsDto":{"type":"object","properties":{"NOT_RECEIVED":{"type":"number"},"PARTIALLY_RECEIVED":{"type":"number"},"FULLY_RECEIVED":{"type":"number"}},"required":["NOT_RECEIVED","PARTIALLY_RECEIVED","FULLY_RECEIVED"]},"ProjectCommittedDto":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"projectCode":{"type":"string","example":"KRR-001"},"projectName":{"type":"string","example":"Kampala Ring Road"},"currency":{"type":"string","nullable":true,"example":"UGX"},"amount":{"type":"string","example":"640000000.0000"},"count":{"type":"number","description":"Committing orders on this project."}},"required":["projectId","projectCode","projectName","amount","count"]},"PurchaseOrderSummaryDto":{"type":"object","properties":{"orderCount":{"type":"number","description":"Every matching order, in any status."},"statusCounts":{"$ref":"#/components/schemas/PurchaseOrderStatusCountsDto"},"committed":{"description":"ISSUED and CLOSED orders — what the organization has committed itself to. Drafts and cancelled orders commit nothing.","type":"array","items":{"$ref":"#/components/schemas/ProcurementCurrencyTotalDto"}},"open":{"description":"ISSUED orders only: committed and not yet closed.","type":"array","items":{"$ref":"#/components/schemas/ProcurementCurrencyTotalDto"}},"draft":{"description":"DRAFT orders: prepared, commits nothing until issued.","type":"array","items":{"$ref":"#/components/schemas/ProcurementCurrencyTotalDto"}},"receiptCounts":{"description":"Committing (ISSUED and CLOSED) orders goods can be received against, by how much has arrived — derived from POSTED goods receipts. Cash orders are excluded: they are settled, not delivered.","allOf":[{"$ref":"#/components/schemas/PurchaseOrderReceiptCountsDto"}]},"byProject":{"description":"Committed value per project and currency, largest first. Projects with no committing order are absent.","type":"array","items":{"$ref":"#/components/schemas/ProjectCommittedDto"}}},"required":["orderCount","statusCounts","committed","open","draft","receiptCounts","byProject"]},"GoodsReceiptStatusCountsDto":{"type":"object","properties":{"DRAFT":{"type":"number"},"POSTED":{"type":"number"},"CANCELLED":{"type":"number"}},"required":["DRAFT","POSTED","CANCELLED"]},"GoodsReceiptSummaryDto":{"type":"object","properties":{"statusCounts":{"$ref":"#/components/schemas/GoodsReceiptStatusCountsDto"},"received":{"description":"POSTED receipts valued at their order lines’ agreed unit prices, in the order’s currency. A draft attests nothing and a cancelled receipt counts for nothing.","type":"array","items":{"$ref":"#/components/schemas/ProcurementCurrencyTotalDto"}}},"required":["statusCounts","received"]},"RequisitionStatusCountsDto":{"type":"object","properties":{"DRAFT":{"type":"number"},"SUBMITTED":{"type":"number"},"APPROVED":{"type":"number"},"REJECTED":{"type":"number"},"CANCELLED":{"type":"number"}},"required":["DRAFT","SUBMITTED","APPROVED","REJECTED","CANCELLED"]},"RequisitionPipelineDto":{"type":"object","properties":{"statusCounts":{"$ref":"#/components/schemas/RequisitionStatusCountsDto"},"awaitingApproval":{"description":"SUBMITTED requisitions at their estimated value, per currency. An estimate, not a commitment.","type":"array","items":{"$ref":"#/components/schemas/ProcurementCurrencyTotalDto"}},"readyToOrderCount":{"type":"number","description":"APPROVED requisitions with at least one line not yet fully covered by ISSUED or CLOSED orders."},"approvedForProcurementCount":{"type":"number","description":"APPROVED requisitions Procurement works on: those with at least one line that is not paid directly (or no lines at all). Equal to `statusCounts.APPROVED` until a requisition type is routed to Pay directly."}},"required":["statusCounts","awaitingApproval","readyToOrderCount","approvedForProcurementCount"]},"BudgetCommitmentLineDto":{"type":"object","properties":{"budgetLineId":{"type":"string","format":"uuid"},"description":{"type":"string","example":"Concrete to substructure, incl. 5% wastage"},"boqItemCode":{"type":"string","nullable":true,"example":"C.2.1","description":"The BOQ item the line draws against, if any."},"costCentreCode":{"type":"string","nullable":true,"example":"CC-STR"},"authorizedAmount":{"type":"string","example":"1250000000.0000","description":"Revised amount: `amount + variationAmount`."},"committedAmount":{"type":"string","example":"850000000.0000","description":"ISSUED and CLOSED order lines drawing on this budget line."},"pendingAmount":{"type":"string","example":"20000000.0000","description":"Estimates on SUBMITTED and APPROVED requisition lines beyond what orders already commit: `max(requested − committed, 0)`."},"remainingAmount":{"type":"string","example":"380000000.0000","description":"`authorizedAmount − committedAmount − pendingAmount`. **May be negative**; nothing blocks an overrun."}},"required":["budgetLineId","description","authorizedAmount","committedAmount","pendingAmount","remainingAmount"]},"ProjectBudgetCommitmentDto":{"type":"object","properties":{"budgetId":{"type":"string","format":"uuid"},"budgetCode":{"type":"string","example":"BUD-KM-01"},"budgetName":{"type":"string","example":"Main project budget"},"currency":{"type":"string","nullable":true,"example":"UGX"},"authorizedAmount":{"type":"string","example":"4034300000.0000"},"committedAmount":{"type":"string","example":"850000000.0000"},"pendingAmount":{"type":"string","example":"20000000.0000"},"remainingAmount":{"type":"string","example":"3164300000.0000","description":"May be negative."},"lineCount":{"type":"number","description":"Every line on the budget."},"overrunLineCount":{"type":"number","description":"Lines whose committed and pending claims exceed what they authorize."},"lines":{"description":"Lines with anything committed or pending, largest commitment first. Untouched lines are absent.","type":"array","items":{"$ref":"#/components/schemas/BudgetCommitmentLineDto"}},"otherCurrencyCommitted":{"description":"Committing orders drawn on this budget in a currency other than its own — excluded from every figure above, never converted.","type":"array","items":{"$ref":"#/components/schemas/ProcurementCurrencyTotalDto"}},"outsideBudgetCommitted":{"description":"Committing orders on this project drawn on no line of this budget — a line of a closed budget, or none at all — per currency.","type":"array","items":{"$ref":"#/components/schemas/ProcurementCurrencyTotalDto"}}},"required":["budgetId","budgetCode","budgetName","authorizedAmount","committedAmount","pendingAmount","remainingAmount","lineCount","overrunLineCount","lines","otherCurrencyCommitted","outsideBudgetCommitted"]},"ProcurementSummaryDto":{"type":"object","properties":{"purchaseOrders":{"$ref":"#/components/schemas/PurchaseOrderSummaryDto"},"receipts":{"nullable":true,"description":"`null` unless you hold `goods_receipt.view` — never an empty section.","type":"object","allOf":[{"$ref":"#/components/schemas/GoodsReceiptSummaryDto"}]},"requisitions":{"nullable":true,"description":"`null` unless you hold `requisition.view` — never an empty section.","type":"object","allOf":[{"$ref":"#/components/schemas/RequisitionPipelineDto"}]},"budget":{"nullable":true,"description":"`null` unless `projectId` is given and you hold `budget.view`, or when that project has no ACTIVE budget.","type":"object","allOf":[{"$ref":"#/components/schemas/ProjectBudgetCommitmentDto"}]}},"required":["purchaseOrders"]},"CreateGoodsReceiptLineDto":{"type":"object","properties":{"purchaseOrderLineId":{"type":"string","description":"The ordered item this line receives. Must belong to this receipt's own\npurchase order.","format":"uuid"},"quantity":{"type":"string","description":"How much arrived, as a decimal string — never a JSON number.\n\n**The decorator order below is load-bearing.** The global pipe runs with\n`enableImplicitConversion`, which has already turned a JSON `0.5` into\n`\"0.5\"` by the time `@IsString` sees it. `@Transform(rejectNumericMoney)`\nreads the untouched payload and substitutes `NaN`, which fails both the\ntype and the pattern — so it must sit above them.","example":"60.0000"},"description":{"type":"string","description":"What actually turned up, if it differs from what was ordered. Defaults to\nthe order line's description.","example":"OPC 32.5N cement — 8 bags torn, accepted","maxLength":2000},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}},"required":["purchaseOrderLineId","quantity"]},"CreateGoodsReceiptDto":{"type":"object","properties":{"purchaseOrderId":{"type":"string","description":"The issued purchase order these goods arrived against.\n\nThe only thing the client names. Project, tenant and supplier all follow\nfrom it.","format":"uuid"},"receivedDate":{"type":"string","description":"The date the goods physically arrived, as `YYYY-MM-DD`.\n\nOptional, and defaulted to today when the receipt is posted. Backdating is\nallowed on purpose: a delivery keyed in a week late is ordinary site\nreality, and refusing it only pushes people to record a date they know is\nwrong.","example":"2026-09-22"},"deliveryNoteNumber":{"type":"string","description":"The supplier's own delivery note reference, as printed on the paper that\ncame with the lorry. Not unique — suppliers reuse their own numbering.","example":"DN-48211","maxLength":64},"deliveryLocation":{"type":"string","description":"Where the goods were actually unloaded, in your own words.","example":"Gate 2, batching plant hardstanding","maxLength":200},"storeId":{"type":"string","description":"The store the goods went into — the balance a posted receipt moves (D.10).\n\nOptional here and required only at posting, and only when a line actually\nmoves stock: a receipt for haulage or consultancy never needs one. Distinct\nfrom `deliveryLocation`, which says where the lorry stopped in the\nstorekeeper's own words; this says which balance the goods joined.","format":"uuid"},"storeLocationId":{"type":"string","description":"The bin inside `storeId` the delivery was put down in (D.10). Optional:\nomitted means \"in the store, no bin recorded\". Must belong to `storeId`.","format":"uuid"},"notes":{"type":"string","maxLength":2000},"lines":{"description":"Lines may be sent with the receipt, or added afterwards while it is a draft.","type":"array","items":{"$ref":"#/components/schemas/CreateGoodsReceiptLineDto"}}},"required":["purchaseOrderId"]},"GoodsReceiptLineDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"goodsReceiptId":{"type":"string"},"projectId":{"type":"string"},"purchaseOrderId":{"type":"string"},"purchaseOrderLineId":{"type":"string"},"description":{"type":"string"},"unit":{"type":"string","description":"Copied from the order line; not editable."},"quantity":{"type":"string","example":"60.0000","description":"A decimal string."},"sortOrder":{"type":"number"},"purchaseOrderLineDescription":{"type":"string","nullable":true,"description":"What the order line says, for comparison."},"orderedQuantity":{"type":"string","nullable":true,"example":"100.0000"},"unitPrice":{"type":"string","nullable":true,"example":"12000.00"},"lineValue":{"type":"string","nullable":true,"description":"This line’s quantity at the order’s agreed price. Derived on read."},"previouslyReceivedQuantity":{"type":"string","nullable":true,"description":"Posted quantity against this order line on other receipts, excluding this one."},"remainingQuantity":{"type":"string","nullable":true,"description":"Ordered less what other posted receipts already account for. A draft may exceed it; posting will refuse."},"requisitionLineId":{"type":"string","nullable":true},"budgetLineId":{"type":"string","nullable":true},"boqItemCode":{"type":"string","nullable":true},"costCentreCode":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","goodsReceiptId","projectId","purchaseOrderId","purchaseOrderLineId","description","unit","quantity","sortOrder","createdAt","updatedAt"]},"GoodsReceiptDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","description":"Always the caller’s own organization."},"projectId":{"type":"string","description":"Taken from the purchase order, never the body."},"purchaseOrderId":{"type":"string"},"purchaseOrderNumber":{"type":"string","nullable":true},"supplierId":{"type":"string","nullable":true},"supplierCode":{"type":"string","nullable":true},"supplierName":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true,"description":"The project’s name, joined in for display. Receipt numbers restart in every project."},"projectCode":{"type":"string","nullable":true,"example":"KRR-001"},"currency":{"type":"string","nullable":true,"example":"UGX","description":"The purchase order’s currency, joined in. `totalValue` is priced at that order’s unit prices, so this is its unit."},"goodsReceiptNumber":{"type":"string","example":"GRN-0001","description":"Sequential per project."},"status":{"enum":["DRAFT","POSTED","CANCELLED"],"type":"string"},"receivedDate":{"type":"string","nullable":true,"description":"Date the goods arrived. Always set once posted."},"deliveryNoteNumber":{"type":"string","nullable":true},"deliveryLocation":{"type":"string","nullable":true},"storeId":{"type":"string","nullable":true,"description":"The store a posted receipt moved stock into, if any (D.10).","format":"uuid"},"storeLocationId":{"type":"string","nullable":true,"description":"The bin inside the store the delivery was put down in, if any (D.10).","format":"uuid"},"notes":{"type":"string","nullable":true},"receivedByMembershipId":{"type":"string"},"receivedByName":{"type":"string","nullable":true},"postedByMembershipId":{"type":"string","nullable":true},"postedByName":{"type":"string","nullable":true},"postedAt":{"format":"date-time","type":"string","nullable":true},"cancelledByMembershipId":{"type":"string","nullable":true},"cancelledByName":{"type":"string","nullable":true},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"lineCount":{"type":"number","description":"Number of lines on this receipt."},"totalValue":{"type":"string","example":"1200000.0000","description":"Received quantity valued at the order’s agreed unit prices, as a decimal string. Derived on read — a receipt stores no price of its own."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/GoodsReceiptLineDto"}},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","purchaseOrderId","goodsReceiptNumber","status","receivedByMembershipId","lineCount","totalValue","createdAt","updatedAt"]},"UpdateGoodsReceiptDto":{"type":"object","properties":{"receivedDate":{"type":"string"},"deliveryNoteNumber":{"type":"string","maxLength":64},"deliveryLocation":{"type":"string","maxLength":200},"storeId":{"type":"string","description":"Set or change the store, while the receipt is still a draft (D.10).\n\nEditable only until posting, like everything else here — after that the\nmovements naming this store are already in the ledger, and re-pointing the\nreceipt would leave them describing a delivery into somewhere it never went.","format":"uuid"},"storeLocationId":{"type":"string","description":"Set or change the bin, while the receipt is still a draft (D.10). Must\nbelong to the receipt's store — or to `storeId` when both are sent. If only\nthe store changes, a bin that is not in the new store is refused rather\nthan silently dropped.","format":"uuid"},"notes":{"type":"string","maxLength":2000}}},"CancelGoodsReceiptDto":{"type":"object","properties":{"reason":{"type":"string","description":"Why this receipt is being cancelled or reversed. **Required** — reversing a\nposted receipt voids an attestation that has already counted against an\norder, and `ck_goods_receipt_cancelled_has_reason` enforces it in the\ndatabase too.","example":"Keyed against the wrong order — goods belong to PO-0044.","maxLength":1000}},"required":["reason"]},"UpdateGoodsReceiptLineDto":{"type":"object","properties":{"quantity":{"type":"string"},"description":{"type":"string","maxLength":2000},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}}},"PurchaseOrderReceivingDto":{"type":"object","properties":{"purchaseOrderLineId":{"type":"string"},"description":{"type":"string"},"unit":{"type":"string"},"orderedQuantity":{"type":"string","example":"100.0000"},"receivedQuantity":{"type":"string","example":"60.0000","description":"Summed over POSTED receipts only. Drafts and cancelled receipts count for nothing."},"remainingQuantity":{"type":"string","example":"40.0000","description":"Ordered less received. Never negative."},"receivedValue":{"type":"string","example":"720000.0000","description":"Received quantity at the order’s agreed unit price."},"receiptStatus":{"enum":["NOT_RECEIVED","PARTIALLY_RECEIVED","FULLY_RECEIVED"],"type":"string","description":"Derived on every read, never stored — see PurchaseOrderReceiptStatus."},"receivable":{"type":"boolean","description":"Whether goods can arrive against this line: its requisition line’s type is receivable. A Cash line on an order that also carries Material is `false`, and a receipt naming it is refused."}},"required":["purchaseOrderLineId","description","unit","orderedQuantity","receivedQuantity","remainingQuantity","receivedValue","receiptStatus","receivable"]},"CreateStockItemDto":{"type":"object","properties":{"code":{"type":"string","description":"Short stable identifier, unique within the organization.\n\nUpper-cased on the way in, matching every other master-data code: without\nit `cem-42.5n` and `CEM-42.5N` become two items the unique constraint is\nhappy to accept, and the ledger splits one material across two balances.\n\nOmit (or send blank) to have one generated from the category and name —\n`MAT-CEM-PORTLAND-CEMENT` — numbered `-2`, `-3`… if already taken.","example":"CEM-42.5N","maxLength":32},"name":{"type":"string","maxLength":200,"example":"Portland Cement 42.5N"},"description":{"type":"string","maxLength":500},"baseUnit":{"type":"string","description":"The unit every quantity of this item is counted in.\n\nFree text, matching `boq_item.unit` and the three line tables — nothing\nconverts between units anywhere in this system, so this is a label the\nledger carries rather than a dimension it reasons about.","example":"bag","maxLength":16},"isStockControlled":{"type":"boolean","description":"Whether receiving this item moves stock. Defaults true.\n\nSet false for something bought and received but never held — consultancy,\nsubcontract work, plant hire. This is the ONLY place that question is\nanswered; `requisition_type.is_receivable` asks whether goods may arrive at\nall, which is a different question on a different table.","default":true},"categoryId":{"type":"string","description":"The category it is filed under. Omit to file it under \"Uncategorised\",\ncreated on first use — so an older client that knows nothing of\ncategories still works, and the item is plainly marked as needing one.","format":"uuid"},"subcategoryId":{"type":"string","description":"Must be a subcategory of `categoryId`.","format":"uuid"},"itemType":{"enum":["MATERIAL","EQUIPMENT"],"type":"string","default":"MATERIAL"},"preferredSupplierId":{"type":"string","format":"uuid"},"unitCost":{"type":"string","description":"What one base unit costs, as far as anyone knows before it is first\nreceived. Becomes the item's average cost until the first priced receipt,\nwhich replaces it — the item holds nothing until then, so the weighted\naverage starts from the receipt alone.","example":"33500.0000"},"reorderLevel":{"type":"string","description":"The warehouse quantity, in the base unit, at or below which the item is\nlow. Omit for none: an item with no reorder level is never reported low.","nullable":true,"example":"400.0000"}},"required":["name","baseUnit"]},"StockItemDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"baseUnit":{"type":"string"},"isStockControlled":{"type":"boolean"},"itemType":{"enum":["MATERIAL","EQUIPMENT"],"type":"string"},"categoryId":{"type":"string","format":"uuid"},"categoryName":{"type":"string"},"subcategoryId":{"type":"string","nullable":true,"format":"uuid"},"subcategoryName":{"type":"string","nullable":true},"categoryPath":{"type":"string","example":"Waterproofing › Membranes","description":"Category, then subcategory if any, joined by \" › \"."},"reorderLevel":{"type":"string","nullable":true,"example":"400.0000"},"preferredSupplierId":{"type":"string","nullable":true,"format":"uuid"},"preferredSupplierName":{"type":"string","nullable":true},"mergedIntoStockItemId":{"type":"string","nullable":true,"format":"uuid","description":"Set when this item was merged into another as a duplicate."},"averageUnitCost":{"type":"string","nullable":true,"example":"33500.0000","description":"Weighted-average cost of one base unit, kept by the ledger. Null until a priced receipt. Read-only."},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"photoUrl":{"type":"string","nullable":true,"description":"The item photo, within 1600 px on its longest side, WebP. Null when the item has none."},"photoThumbUrl":{"type":"string","nullable":true,"description":"A 160 px square crop of the photo, WebP."},"photoUpdatedAt":{"format":"date-time","type":"string","nullable":true,"description":"When the photo was last added, replaced or removed. Null if it never had one."},"photoUpdatedByName":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","code","name","description","baseUnit","isStockControlled","itemType","categoryId","categoryName","subcategoryId","subcategoryName","categoryPath","reorderLevel","preferredSupplierId","preferredSupplierName","mergedIntoStockItemId","averageUnitCost","status","photoUrl","photoThumbUrl","photoUpdatedAt","photoUpdatedByName","createdAt","updatedAt"]},"SimilarStockItemDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"categoryPath":{"type":"string"},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"similarity":{"type":"number","description":"How alike the names are, 0 to 1, after case and punctuation."}},"required":["id","code","name","categoryPath","status","similarity"]},"StockItemCodeAvailabilityDto":{"type":"object","properties":{"code":{"type":"string"},"available":{"type":"boolean"}},"required":["code","available"]},"StockItemEventDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventType":{"enum":["CREATED","UPDATED","RECATEGORISED","DEACTIVATED","REACTIVATED","MERGED_INTO","MERGED_FROM","PHOTO_ADDED","PHOTO_REPLACED","PHOTO_REMOVED","COST_CHANGED"],"type":"string"},"summary":{"type":"string"},"actorName":{"type":"string","nullable":true},"occurredAt":{"format":"date-time","type":"string"}},"required":["id","eventType","summary","actorName","occurredAt"]},"MergeLineCountDto":{"type":"object","properties":{"label":{"type":"string","example":"Material issue lines"},"count":{"type":"number"}},"required":["label","count"]},"StockItemMergePreviewDto":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/StockItemDto"},"target":{"$ref":"#/components/schemas/StockItemDto"},"sourceOnHand":{"type":"string","example":"120.0000","description":"What the source holds across every store; moves to the target."},"sourceStoreCount":{"type":"number","description":"Stores where the source holds stock."},"movementCount":{"type":"number","description":"Ledger movements that move to the target."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/MergeLineCountDto"}},"blockers":{"description":"Why the merge cannot go ahead now, in words to show. Empty when it can.","type":"array","items":{"type":"string"}}},"required":["source","target","sourceOnHand","sourceStoreCount","movementCount","lines","blockers"]},"MergeStockItemDto":{"type":"object","properties":{"targetStockItemId":{"type":"string","description":"The item that stays. The one in the path is folded into it.","format":"uuid"}},"required":["targetStockItemId"]},"UpdateStockItemDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"baseUnit":{"type":"string","maxLength":16},"isStockControlled":{"type":"boolean","description":"Turning this off stops FUTURE receipts creating movements. It does not\nremove the movements already in the ledger, and must not: a balance that\nsilently changed because somebody edited a catalogue flag would make the\nledger unexplainable, which is the one property it exists to have."},"categoryId":{"type":"string","description":"Re-files the item. Changing the category without sending\n`subcategoryId` clears the subcategory, which belonged to the old one.","format":"uuid"},"subcategoryId":{"type":"string","nullable":true,"description":"`null` clears it. Must be a subcategory of the item's category.","format":"uuid"},"preferredSupplierId":{"type":"string","nullable":true,"description":"`null` clears it.","format":"uuid"},"reorderLevel":{"type":"string","nullable":true,"description":"`null` clears it: the item is then never reported low.","example":"400.0000"},"status":{"description":"Deactivated rather than deleted — movements reference an item forever.\nRefused while any store holds the item (`409 STOCK_ITEM_HAS_STOCK`).","enum":["ACTIVE","INACTIVE"],"type":"string"}}},"ProposeStockItemCostDto":{"type":"object","properties":{"unitCost":{"type":"string","description":"What one base unit should cost from now on.","example":"33500.0000"},"reason":{"type":"string","maxLength":1000,"example":"Supplier price list of 1 Nov"}},"required":["unitCost","reason"]},"StockItemCostChangeDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string"},"stockItemName":{"type":"string"},"baseUnit":{"type":"string"},"status":{"enum":["PENDING","APPROVED","REJECTED"],"type":"string"},"previousCost":{"type":"string","nullable":true,"example":"30000.0000"},"proposedCost":{"type":"string","example":"33500.0000"},"reason":{"type":"string"},"proposedByMembershipId":{"type":"string","format":"uuid"},"proposedByName":{"type":"string","nullable":true},"proposedAt":{"format":"date-time","type":"string"},"decidedByName":{"type":"string","nullable":true},"decidedAt":{"format":"date-time","type":"string","nullable":true},"decisionNote":{"type":"string","nullable":true},"isMine":{"type":"boolean","description":"True when the caller proposed it, so cannot approve it."}},"required":["id","stockItemId","stockItemCode","stockItemName","baseUnit","status","previousCost","proposedCost","reason","proposedByMembershipId","proposedByName","proposedAt","decidedByName","decidedAt","decisionNote","isMine"]},"StockItemCostDecisionDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000,"example":"Does not match the invoice"}},"required":["reason"]},"StockSubcategoryNodeDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"sortOrder":{"type":"number"},"itemCount":{"type":"number","description":"Active items filed under this subcategory."}},"required":["id","name","sortOrder","itemCount"]},"StockCategoryNodeDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"sortOrder":{"type":"number"},"itemCount":{"type":"number","description":"Active items filed under this category, subcategories included."},"withoutSubcategoryCount":{"type":"number","description":"Of those, how many have no subcategory."},"subcategories":{"type":"array","items":{"$ref":"#/components/schemas/StockSubcategoryNodeDto"}}},"required":["id","name","sortOrder","itemCount","withoutSubcategoryCount","subcategories"]},"StockCategoryTreeDto":{"type":"object","properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/StockCategoryNodeDto"}},"categoryCount":{"type":"number"},"subcategoryCount":{"type":"number"}},"required":["categories","categoryCount","subcategoryCount"]},"CreateStockCategoryDto":{"type":"object","properties":{"name":{"type":"string","maxLength":100,"example":"Waterproofing"},"parentId":{"type":"string","description":"The category this is a subcategory of. Omit for a top-level category.","format":"uuid"}},"required":["name"]},"StockCategoryDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parentId":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string"},"sortOrder":{"type":"number"}},"required":["id","parentId","name","sortOrder"]},"ReorderStockCategoriesDto":{"type":"object","properties":{"parentId":{"type":"string","nullable":true,"format":"uuid"},"orderedIds":{"uniqueItems":true,"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["parentId","orderedIds"]},"UpdateStockCategoryDto":{"type":"object","properties":{"name":{"type":"string","maxLength":100}}},"CreateStoreDto":{"type":"object","properties":{"code":{"type":"string","maxLength":32,"example":"MAIN"},"name":{"type":"string","maxLength":200,"example":"Main Store"},"description":{"type":"string","maxLength":500},"projectId":{"type":"string","description":"The site this store serves, or omitted for a central store.\n\nDescriptive: stock is owned by the store either way, and nothing scopes a\nbalance or a permission by it. It exists so a firm can tell \"Main Store\"\nfrom \"Kampala Mall site store\" in a list.","format":"uuid"}},"required":["code","name"]},"StoreDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"projectId":{"type":"string","nullable":true,"format":"uuid"},"projectName":{"type":"string","nullable":true},"projectCode":{"type":"string","nullable":true},"openStockCountId":{"type":"string","nullable":true,"format":"uuid","description":"The stock count holding this store — counting or awaiting approval. While set, stock cannot leave the store."},"openStockCountNumber":{"type":"string","nullable":true,"example":"CNT-0007"},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","code","name","description","projectId","projectName","projectCode","openStockCountId","openStockCountNumber","status","createdAt","updatedAt"]},"UpdateStoreDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"}}},"CreateStoreLocationDto":{"type":"object","properties":{"code":{"type":"string","maxLength":32,"example":"A1"},"name":{"type":"string","maxLength":200,"example":"Rack A, shelf 1"},"description":{"type":"string","maxLength":500},"locationType":{"description":"Defaults to `BIN`, the only creatable type. `TRANSIT` is refused: each store\nhas exactly one, provisioned with the store (D.12).","enum":["BIN","TRANSIT"],"type":"string","default":"BIN"}},"required":["code","name"]},"StoreLocationDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"locationType":{"enum":["BIN","TRANSIT"],"type":"string"},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","storeId","code","name","description","locationType","status","createdAt","updatedAt"]},"UpdateStoreLocationDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"}}},"StockBalanceDto":{"type":"object","properties":{"storeId":{"type":"string","nullable":true,"description":"Null only when `groupBy=item`.","format":"uuid"},"storeCode":{"type":"string","nullable":true},"storeName":{"type":"string","nullable":true},"storeLocationId":{"type":"string","nullable":true,"description":"Set only when `groupBy=location`, and even then null for stock in the store\nwith no bin recorded.","format":"uuid"},"storeLocationCode":{"type":"string","nullable":true},"storeLocationName":{"type":"string","nullable":true},"storeLocationType":{"nullable":true,"description":"Set only when `groupBy=location` and a location is recorded. `TRANSIT` is\nstock dispatched from this store and not yet received (D.12).","enum":["BIN","TRANSIT"],"type":"string"},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string"},"stockItemName":{"type":"string"},"baseUnit":{"type":"string"},"quantity":{"type":"string","description":"On-hand quantity as an exact decimal string — the sum of every posted\nmovement for this store and item.","example":"85.0000"},"reserved":{"type":"string","description":"Held for sales awaiting approval — part of `quantity`.","example":"10.0000"},"available":{"type":"string","description":"`quantity` − `reserved`: what an issue, transfer or sale can take. The\nledger refuses anything above it.","example":"75.0000"},"lastMovementAt":{"format":"date-time","type":"string","nullable":true,"description":"When this item last moved in this store."}},"required":["storeId","storeCode","storeName","storeLocationId","storeLocationCode","storeLocationName","storeLocationType","stockItemId","stockItemCode","stockItemName","baseUnit","quantity","reserved","available","lastMovementAt"]},"StockMovementDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"storeCode":{"type":"string","nullable":true},"storeName":{"type":"string","nullable":true},"storeLocationId":{"type":"string","nullable":true,"format":"uuid"},"storeLocationCode":{"type":"string","nullable":true},"storeLocationName":{"type":"string","nullable":true},"storeLocationType":{"nullable":true,"enum":["BIN","TRANSIT"],"type":"string"},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string","nullable":true},"stockItemName":{"type":"string","nullable":true},"baseUnit":{"type":"string","nullable":true,"example":"bag"},"movementType":{"enum":["RECEIPT","ISSUE","TRANSFER","ADJUSTMENT","RETURN","SUPPLIER_RETURN","REVERSAL","SALE"],"type":"string"},"quantity":{"type":"string","description":"Signed, as an exact decimal string. Positive for a receipt, negative for a\nreversal — never a JSON number, which would round a `numeric(18,4)` through\na double on its way to the client.","example":"60.0000"},"unitCost":{"type":"string","nullable":true,"example":"33500.0000","description":"What one unit moved at — fixed when the movement was written. Null when the item had no cost yet."},"projectId":{"type":"string","nullable":true,"format":"uuid"},"projectName":{"type":"string","nullable":true},"projectCode":{"type":"string","nullable":true},"sourceType":{"enum":["GOODS_RECEIPT","MATERIAL_ISSUE","STOCK_TRANSFER","MATERIAL_RETURN","SUPPLIER_RETURN","INVENTORY_ADJUSTMENT","STOCK_COUNT","SALES_ORDER"],"type":"string"},"goodsReceiptId":{"type":"string","nullable":true,"format":"uuid"},"goodsReceiptNumber":{"type":"string","nullable":true},"goodsReceiptLineId":{"type":"string","nullable":true,"format":"uuid"},"materialIssueId":{"type":"string","nullable":true,"format":"uuid"},"materialIssueNumber":{"type":"string","nullable":true},"materialIssueLineId":{"type":"string","nullable":true,"format":"uuid"},"stockTransferId":{"type":"string","nullable":true,"format":"uuid"},"stockTransferNumber":{"type":"string","nullable":true},"stockTransferLineId":{"type":"string","nullable":true,"format":"uuid"},"transferLeg":{"nullable":true,"enum":["SOURCE_OUT","TRANSIT_IN","TRANSIT_OUT","DESTINATION_IN"],"type":"string","description":"For a `TRANSFER`: which of the line’s four rows this is. `SOURCE_OUT` and `TRANSIT_IN` are written at dispatch, `TRANSIT_OUT` and `DESTINATION_IN` at receipt."},"materialReturnId":{"type":"string","nullable":true,"format":"uuid"},"materialReturnNumber":{"type":"string","nullable":true},"materialReturnLineId":{"type":"string","nullable":true,"format":"uuid"},"supplierReturnId":{"type":"string","nullable":true,"format":"uuid"},"supplierReturnNumber":{"type":"string","nullable":true},"supplierReturnLineId":{"type":"string","nullable":true,"format":"uuid"},"inventoryAdjustmentId":{"type":"string","nullable":true,"format":"uuid"},"inventoryAdjustmentNumber":{"type":"string","nullable":true},"inventoryAdjustmentLineId":{"type":"string","nullable":true,"format":"uuid"},"stockCountId":{"type":"string","nullable":true,"format":"uuid"},"stockCountNumber":{"type":"string","nullable":true},"stockCountLineId":{"type":"string","nullable":true,"format":"uuid"},"salesOrderId":{"type":"string","nullable":true,"format":"uuid"},"salesOrderNumber":{"type":"string","nullable":true},"salesOrderLineId":{"type":"string","nullable":true,"format":"uuid"},"stockCountLinePhotoCount":{"type":"number","description":"Evidence photos on the count line this adjustment came from (0 when none, or not from a count). Read them at `GET /stock-counts/{stockCountId}/lines/{stockCountLineId}/photos`."},"reversesMovementId":{"type":"string","nullable":true,"format":"uuid"},"movedByMembershipId":{"type":"string","format":"uuid"},"movedByName":{"type":"string","nullable":true},"movedAt":{"format":"date-time","type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","storeId","storeCode","storeName","storeLocationId","storeLocationCode","storeLocationName","storeLocationType","stockItemId","stockItemCode","stockItemName","baseUnit","movementType","quantity","unitCost","projectId","projectName","projectCode","sourceType","goodsReceiptId","goodsReceiptNumber","goodsReceiptLineId","materialIssueId","materialIssueNumber","materialIssueLineId","stockTransferId","stockTransferNumber","stockTransferLineId","transferLeg","materialReturnId","materialReturnNumber","materialReturnLineId","supplierReturnId","supplierReturnNumber","supplierReturnLineId","inventoryAdjustmentId","inventoryAdjustmentNumber","inventoryAdjustmentLineId","stockCountId","stockCountNumber","stockCountLineId","salesOrderId","salesOrderNumber","salesOrderLineId","stockCountLinePhotoCount","reversesMovementId","movedByMembershipId","movedByName","movedAt","createdAt"]},"InventorySettingsChangeDto":{"type":"object","properties":{"field":{"type":"string","example":"saleApprovalLimit"},"oldValue":{"type":"string","example":"10000000.0000"},"newValue":{"type":"string","example":"1000000.0000"},"changedByName":{"type":"string","nullable":true},"changedAt":{"format":"date-time","type":"string"}},"required":["field","oldValue","newValue","changedByName","changedAt"]},"InventorySettingsDto":{"type":"object","properties":{"countIntervalDays":{"type":"number","example":90,"description":"A store with no posted stock count within this many days is due a count."},"financeApprovalLimit":{"type":"string","example":"2000000.0000","description":"A stock count whose gross variance value is over this needs the finance approval (`stock_count.approve_finance`) after the stores one."},"saleApprovalLimit":{"type":"string","example":"10000000.0000","description":"A sale to a client whose total including VAT is over this needs Finance approval (`sales_order.approve`) before its stock is released. A sale below cost always does."},"unusualUsagePercent":{"type":"number","example":30,"description":"Issues to one site over the last two weeks this many percent above its 8-week weekly average are flagged."},"coverBufferDays":{"type":"number","example":7,"description":"Days of cover under the lead time plus this many days, with nothing on order, warns."},"poDueSoonDays":{"type":"number","example":2,"description":"A purchase order expected within this many days is flagged so a receipt can be prepared."},"serviceDueDays":{"type":"number","example":14,"description":"Equipment whose next service falls within this many days is flagged as due."},"customized":{"type":"boolean","description":"False until the organization changes a threshold; the defaults apply."},"changes":{"description":"The latest 20 threshold changes, newest first.","type":"array","items":{"$ref":"#/components/schemas/InventorySettingsChangeDto"}}},"required":["countIntervalDays","financeApprovalLimit","saleApprovalLimit","unusualUsagePercent","coverBufferDays","poDueSoonDays","serviceDueDays","customized","changes"]},"UpdateInventorySettingsDto":{"type":"object","properties":{"countIntervalDays":{"type":"number","minimum":7,"maximum":730},"financeApprovalLimit":{"type":"string","example":"2000000.0000"},"saleApprovalLimit":{"type":"string","example":"10000000.0000"},"unusualUsagePercent":{"type":"number","minimum":5,"maximum":500},"coverBufferDays":{"type":"number","minimum":0,"maximum":60},"poDueSoonDays":{"type":"number","minimum":0,"maximum":30},"serviceDueDays":{"type":"number","minimum":1,"maximum":90}}},"MaterialIssueDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","description":"Always your own organization."},"projectId":{"type":"string","format":"uuid","description":"Taken from the requisition."},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"requisitionId":{"type":"string","format":"uuid"},"requisitionNumber":{"type":"string","nullable":true},"requisitionPurpose":{"type":"string","nullable":true},"storeId":{"type":"string","format":"uuid"},"storeCode":{"type":"string","nullable":true},"storeName":{"type":"string","nullable":true},"materialIssueNumber":{"type":"string","example":"MIN-0001","description":"Sequential per project."},"status":{"enum":["DRAFT","POSTED","CANCELLED"],"type":"string"},"purpose":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"receiverMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"Who takes custody."},"receiverName":{"type":"string","nullable":true},"createdByMembershipId":{"type":"string","format":"uuid"},"createdByName":{"type":"string","nullable":true},"issuedByMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"Who released the goods — whoever posted."},"issuedByName":{"type":"string","nullable":true},"postedAt":{"format":"date-time","type":"string","nullable":true,"description":"When the goods were released."},"cancelledByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"cancelledByName":{"type":"string","nullable":true},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"lineCount":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","projectCode","projectName","requisitionId","requisitionNumber","requisitionPurpose","storeId","storeCode","storeName","materialIssueNumber","status","purpose","notes","receiverMembershipId","receiverName","createdByMembershipId","createdByName","issuedByMembershipId","issuedByName","postedAt","cancelledByMembershipId","cancelledByName","cancelledAt","cancellationReason","lineCount","createdAt","updatedAt"]},"UpdateMaterialIssueDto":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"receiverMembershipId":{"type":"string","format":"uuid"},"purpose":{"type":"string","maxLength":500},"notes":{"type":"string","maxLength":2000}}},"CancelMaterialIssueDto":{"type":"object","properties":{"reason":{"type":"string","description":"Why. Required for a draft and a posted issue alike; for a posted one it is\nthe record of why stock came back without a return.","maxLength":1000,"example":"Keyed against the wrong bin"}},"required":["reason"]},"MaterialIssueLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"materialIssueId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"requisitionId":{"type":"string","format":"uuid"},"requisitionLineId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"storeLocationId":{"type":"string","nullable":true,"format":"uuid"},"storeLocationCode":{"type":"string","nullable":true},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string","nullable":true},"stockItemName":{"type":"string","nullable":true},"baseUnit":{"type":"string","nullable":true,"description":"The stock item’s base unit."},"quantity":{"type":"string","example":"20.0000"},"notes":{"type":"string","nullable":true},"sortOrder":{"type":"number"},"requisitionLineDescription":{"type":"string","nullable":true,"description":"What the requisition line asks for."},"requestedQuantity":{"type":"string","nullable":true,"example":"100.0000","description":"The approved quantity of the requisition line."},"previouslyIssuedQuantity":{"type":"string","nullable":true,"example":"40.0000","description":"Already issued against the requisition line by other POSTED issues — this issue excluded, so a draft shows the room left for it."},"remainingQuantity":{"type":"string","nullable":true,"example":"60.0000"},"budgetLineId":{"type":"string","nullable":true,"format":"uuid","description":"Cost provenance, joined from the requisition line — never copied."},"boqItemCode":{"type":"string","nullable":true},"costCentreCode":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","materialIssueId","projectId","requisitionId","requisitionLineId","storeId","storeLocationId","storeLocationCode","stockItemId","stockItemCode","stockItemName","baseUnit","quantity","notes","sortOrder","requisitionLineDescription","requestedQuantity","previouslyIssuedQuantity","remainingQuantity","budgetLineId","boqItemCode","costCentreCode","createdAt","updatedAt"]},"CreateMaterialIssueLineDto":{"type":"object","properties":{"requisitionLineId":{"type":"string","description":"A line of the issue's own requisition.","format":"uuid"},"stockItemId":{"type":"string","description":"A stock-controlled item from the catalogue.","format":"uuid"},"storeLocationId":{"type":"string","description":"The bin inside the issue's store to take the goods from. Omit to draw on\nthe store's stock with no bin recorded. Never allocated automatically.","format":"uuid"},"quantity":{"type":"string","description":"In the item's base unit, as an exact decimal string.","example":"20.0000"},"notes":{"type":"string","maxLength":500},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}},"required":["requisitionLineId","stockItemId","quantity"]},"UpdateMaterialIssueLineDto":{"type":"object","properties":{"quantity":{"type":"string","example":"15.0000"},"storeLocationId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":500},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}}},"CreateMaterialIssueDto":{"type":"object","properties":{"requisitionId":{"type":"string","description":"The APPROVED requisition authorizing the issue. Must belong to the project\nin the path; the project and organization follow from it.","format":"uuid"},"storeId":{"type":"string","description":"The store every line draws from.","format":"uuid"},"receiverMembershipId":{"type":"string","description":"The member taking custody. Optional on a draft, required to post.","format":"uuid"},"purpose":{"type":"string","maxLength":500,"example":"Slab pour, block C"},"notes":{"type":"string","maxLength":2000},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateMaterialIssueLineDto"}}},"required":["requisitionId","storeId"]},"RequisitionIssuingLineDto":{"type":"object","properties":{"requisitionLineId":{"type":"string","format":"uuid"},"description":{"type":"string"},"unit":{"type":"string","description":"The requisition’s free-text unit."},"requestedQuantity":{"type":"string","example":"100.0000"},"issuedQuantity":{"type":"string","example":"40.0000","description":"Sum of POSTED issue lines. Drafts and cancelled issues excluded."},"remainingQuantity":{"type":"string","example":"60.0000"},"budgetLineId":{"type":"string","nullable":true,"format":"uuid"},"boqItemCode":{"type":"string","nullable":true},"costCentreCode":{"type":"string","nullable":true}},"required":["requisitionLineId","description","unit","requestedQuantity","issuedQuantity","remainingQuantity","budgetLineId","boqItemCode","costCentreCode"]},"StockTransferDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","description":"Always your own organization."},"projectId":{"type":"string","format":"uuid","description":"Taken from the path."},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"sourceStoreId":{"type":"string","format":"uuid"},"sourceStoreCode":{"type":"string","nullable":true},"sourceStoreName":{"type":"string","nullable":true},"destinationStoreId":{"type":"string","format":"uuid"},"destinationStoreCode":{"type":"string","nullable":true},"destinationStoreName":{"type":"string","nullable":true},"stockTransferNumber":{"type":"string","example":"STN-0001","description":"Sequential per project."},"status":{"enum":["DRAFT","DISPATCHED","RECEIVED","CANCELLED"],"type":"string"},"purpose":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdByMembershipId":{"type":"string","format":"uuid"},"createdByName":{"type":"string","nullable":true},"dispatchedByMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"Who released the goods into transit — whoever dispatched."},"dispatchedByName":{"type":"string","nullable":true},"dispatchedAt":{"format":"date-time","type":"string","nullable":true,"description":"When the goods left."},"receivedByMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"Who confirmed the goods arrived — whoever received."},"receivedByName":{"type":"string","nullable":true},"receivedAt":{"format":"date-time","type":"string","nullable":true,"description":"When the goods arrived."},"cancelledByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"cancelledByName":{"type":"string","nullable":true},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"lineCount":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","projectCode","projectName","sourceStoreId","sourceStoreCode","sourceStoreName","destinationStoreId","destinationStoreCode","destinationStoreName","stockTransferNumber","status","purpose","notes","createdByMembershipId","createdByName","dispatchedByMembershipId","dispatchedByName","dispatchedAt","receivedByMembershipId","receivedByName","receivedAt","cancelledByMembershipId","cancelledByName","cancelledAt","cancellationReason","lineCount","createdAt","updatedAt"]},"UpdateStockTransferDto":{"type":"object","properties":{"sourceStoreId":{"type":"string","format":"uuid"},"destinationStoreId":{"type":"string","format":"uuid"},"purpose":{"type":"string","maxLength":500},"notes":{"type":"string","maxLength":2000}}},"CancelStockTransferDto":{"type":"object","properties":{"reason":{"type":"string","description":"Why the draft is being abandoned.","maxLength":1000,"example":"Raised against the wrong store"}},"required":["reason"]},"StockTransferLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"stockTransferId":{"type":"string","format":"uuid"},"sourceStoreId":{"type":"string","format":"uuid"},"sourceLocationId":{"type":"string","nullable":true,"format":"uuid"},"sourceLocationCode":{"type":"string","nullable":true},"destinationStoreId":{"type":"string","format":"uuid"},"destinationLocationId":{"type":"string","nullable":true,"format":"uuid"},"destinationLocationCode":{"type":"string","nullable":true},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string","nullable":true},"stockItemName":{"type":"string","nullable":true},"baseUnit":{"type":"string","nullable":true,"description":"The stock item’s base unit."},"quantity":{"type":"string","example":"60.0000"},"notes":{"type":"string","nullable":true},"sortOrder":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","stockTransferId","sourceStoreId","sourceLocationId","sourceLocationCode","destinationStoreId","destinationLocationId","destinationLocationCode","stockItemId","stockItemCode","stockItemName","baseUnit","quantity","notes","sortOrder","createdAt","updatedAt"]},"CreateStockTransferLineDto":{"type":"object","properties":{"stockItemId":{"type":"string","description":"A stock-controlled item from the catalogue.","format":"uuid"},"sourceLocationId":{"type":"string","description":"The bin inside the source store the goods leave. Omit to draw on the\nstore's stock with no bin recorded. Never allocated automatically.","format":"uuid"},"destinationLocationId":{"type":"string","description":"The bin inside the destination store the goods go into. Omit to put them\nin the store with no bin recorded.","format":"uuid"},"quantity":{"type":"string","description":"In the item's base unit, as an exact decimal string.","example":"60.0000"},"notes":{"type":"string","maxLength":500},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}},"required":["stockItemId","quantity"]},"UpdateStockTransferLineDto":{"type":"object","properties":{"quantity":{"type":"string","example":"50.0000"},"sourceLocationId":{"type":"string","format":"uuid"},"destinationLocationId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":500},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}}},"CreateStockTransferDto":{"type":"object","properties":{"sourceStoreId":{"type":"string","description":"Where the goods leave from. A central store, or a site store of the\nproject in the path.","format":"uuid"},"destinationStoreId":{"type":"string","description":"Where the goods go. A central store, or a site store of the project in the\npath. May be the source store, to move stock between two of its bins.","format":"uuid"},"purpose":{"type":"string","maxLength":500,"example":"Surplus cement to block C"},"notes":{"type":"string","maxLength":2000},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateStockTransferLineDto"}}},"required":["sourceStoreId","destinationStoreId"]},"MaterialReturnDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"materialIssueId":{"type":"string","format":"uuid"},"materialIssueNumber":{"type":"string","nullable":true},"storeId":{"type":"string","format":"uuid"},"storeCode":{"type":"string","nullable":true},"storeName":{"type":"string","nullable":true},"materialReturnNumber":{"type":"string","example":"MRT-0001","description":"Sequential per project."},"status":{"enum":["DRAFT","POSTED","CANCELLED"],"type":"string"},"reason":{"type":"string"},"notes":{"type":"string","nullable":true},"returnedByMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"Who brought the goods back from site."},"returnedByName":{"type":"string","nullable":true},"createdByMembershipId":{"type":"string","format":"uuid"},"createdByName":{"type":"string","nullable":true},"receivedByMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"Who took the goods back into the store — whoever posted."},"receivedByName":{"type":"string","nullable":true},"postedAt":{"format":"date-time","type":"string","nullable":true},"cancelledByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"cancelledByName":{"type":"string","nullable":true},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"lineCount":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","projectCode","projectName","materialIssueId","materialIssueNumber","storeId","storeCode","storeName","materialReturnNumber","status","reason","notes","returnedByMembershipId","returnedByName","createdByMembershipId","createdByName","receivedByMembershipId","receivedByName","postedAt","cancelledByMembershipId","cancelledByName","cancelledAt","cancellationReason","lineCount","createdAt","updatedAt"]},"UpdateMaterialReturnDto":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"reason":{"type":"string","maxLength":1000},"returnedByMembershipId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":2000}}},"CancelMaterialReturnDto":{"type":"object","properties":{"reason":{"type":"string","description":"Why. For a posted return, the record of why stock that was booked back in\nis being taken out again — the goods never actually came back.","maxLength":1000,"example":"Keyed twice; goods still on site"}},"required":["reason"]},"MaterialReturnLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"materialReturnId":{"type":"string","format":"uuid"},"materialIssueId":{"type":"string","format":"uuid"},"materialIssueLineId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"storeLocationId":{"type":"string","nullable":true,"format":"uuid"},"storeLocationCode":{"type":"string","nullable":true},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string","nullable":true},"stockItemName":{"type":"string","nullable":true},"baseUnit":{"type":"string","nullable":true,"description":"The stock item’s base unit."},"quantity":{"type":"string","example":"12.0000"},"notes":{"type":"string","nullable":true},"sortOrder":{"type":"number"},"issuedQuantity":{"type":"string","nullable":true,"example":"100.0000","description":"What the issue line released."},"previouslyReturnedQuantity":{"type":"string","nullable":true,"example":"30.0000","description":"Already returned against the issue line by other POSTED returns — this return excluded, so a draft shows the room left for it."},"returnableQuantity":{"type":"string","nullable":true,"example":"70.0000"},"requisitionLineId":{"type":"string","nullable":true,"format":"uuid","description":"Cost provenance, joined from the issue line’s requisition line — never copied."},"budgetLineId":{"type":"string","nullable":true,"format":"uuid"},"boqItemCode":{"type":"string","nullable":true},"costCentreCode":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","materialReturnId","materialIssueId","materialIssueLineId","storeId","storeLocationId","storeLocationCode","stockItemId","stockItemCode","stockItemName","baseUnit","quantity","notes","sortOrder","issuedQuantity","previouslyReturnedQuantity","returnableQuantity","requisitionLineId","budgetLineId","boqItemCode","costCentreCode","createdAt","updatedAt"]},"CreateMaterialReturnLineDto":{"type":"object","properties":{"materialIssueLineId":{"type":"string","description":"A line of the return's own material issue.","format":"uuid"},"storeLocationId":{"type":"string","description":"The bin inside the return's store the goods go into. Omit for the store's\nunbinned stock. Never the bin they came from automatically, and never a\ntransit location.","format":"uuid"},"quantity":{"type":"string","description":"In the item's base unit, as an exact decimal string.","example":"12.0000"},"notes":{"type":"string","maxLength":500,"example":"2 bags damp, accepted"},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}},"required":["materialIssueLineId","quantity"]},"UpdateMaterialReturnLineDto":{"type":"object","properties":{"quantity":{"type":"string","example":"10.0000"},"storeLocationId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":500},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}}},"CreateMaterialReturnDto":{"type":"object","properties":{"materialIssueId":{"type":"string","description":"The POSTED material issue the material went out on. Must belong to the\nproject in the path.","format":"uuid"},"storeId":{"type":"string","description":"The store the goods come back into: central, or this project's own site\nstore. Not necessarily the store the issue drew from.","format":"uuid"},"reason":{"type":"string","description":"Why it came back. Required — the return's own evidence.","maxLength":1000,"example":"Slab poured; surplus returned"},"returnedByMembershipId":{"type":"string","description":"The member who brought it back from site. Optional on a draft.","format":"uuid"},"notes":{"type":"string","maxLength":2000},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateMaterialReturnLineDto"}}},"required":["materialIssueId","storeId","reason"]},"MaterialIssueReturnableLineDto":{"type":"object","properties":{"materialIssueLineId":{"type":"string","format":"uuid"},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string"},"stockItemName":{"type":"string"},"baseUnit":{"type":"string"},"issuedQuantity":{"type":"string","example":"100.0000"},"returnedQuantity":{"type":"string","example":"30.0000","description":"Sum of POSTED return lines. Drafts and cancelled excluded."},"returnableQuantity":{"type":"string","example":"70.0000"},"requisitionLineId":{"type":"string","format":"uuid"},"budgetLineId":{"type":"string","nullable":true,"format":"uuid"},"boqItemCode":{"type":"string","nullable":true},"costCentreCode":{"type":"string","nullable":true}},"required":["materialIssueLineId","stockItemId","stockItemCode","stockItemName","baseUnit","issuedQuantity","returnedQuantity","returnableQuantity","requisitionLineId","budgetLineId","boqItemCode","costCentreCode"]},"SupplierReturnDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"goodsReceiptId":{"type":"string","format":"uuid"},"goodsReceiptNumber":{"type":"string","nullable":true},"purchaseOrderId":{"type":"string","format":"uuid"},"purchaseOrderNumber":{"type":"string","nullable":true},"supplierId":{"type":"string","nullable":true,"format":"uuid"},"supplierCode":{"type":"string","nullable":true},"supplierName":{"type":"string","nullable":true},"storeId":{"type":"string","format":"uuid"},"storeCode":{"type":"string","nullable":true},"storeName":{"type":"string","nullable":true},"supplierReturnNumber":{"type":"string","example":"SRN-0001","description":"Sequential per project."},"status":{"enum":["DRAFT","POSTED","CANCELLED"],"type":"string"},"reason":{"type":"string"},"supplierReference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdByMembershipId":{"type":"string","format":"uuid"},"createdByName":{"type":"string","nullable":true},"postedByMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"Who released the goods to the supplier — whoever posted."},"postedByName":{"type":"string","nullable":true},"postedAt":{"format":"date-time","type":"string","nullable":true},"cancelledByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"cancelledByName":{"type":"string","nullable":true},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"lineCount":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","projectCode","projectName","goodsReceiptId","goodsReceiptNumber","purchaseOrderId","purchaseOrderNumber","supplierId","supplierCode","supplierName","storeId","storeCode","storeName","supplierReturnNumber","status","reason","supplierReference","notes","createdByMembershipId","createdByName","postedByMembershipId","postedByName","postedAt","cancelledByMembershipId","cancelledByName","cancelledAt","cancellationReason","lineCount","createdAt","updatedAt"]},"UpdateSupplierReturnDto":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"reason":{"type":"string","maxLength":1000},"supplierReference":{"type":"string","maxLength":100},"notes":{"type":"string","maxLength":2000}}},"CancelSupplierReturnDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000,"example":"Supplier refused collection"}},"required":["reason"]},"SupplierReturnLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"supplierReturnId":{"type":"string","format":"uuid"},"goodsReceiptId":{"type":"string","format":"uuid"},"goodsReceiptLineId":{"type":"string","format":"uuid"},"purchaseOrderLineId":{"type":"string","nullable":true,"format":"uuid"},"receiptLineDescription":{"type":"string","nullable":true},"storeId":{"type":"string","format":"uuid"},"storeLocationId":{"type":"string","nullable":true,"format":"uuid"},"storeLocationCode":{"type":"string","nullable":true},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string","nullable":true},"stockItemName":{"type":"string","nullable":true},"baseUnit":{"type":"string","nullable":true},"quantity":{"type":"string","example":"8.0000"},"notes":{"type":"string","nullable":true},"sortOrder":{"type":"number"},"receivedQuantity":{"type":"string","nullable":true,"example":"100.0000","description":"What the receipt line received."},"previouslyReturnedQuantity":{"type":"string","nullable":true,"example":"10.0000","description":"Already sent back against the receipt line by other POSTED supplier returns — this return excluded."},"returnableQuantity":{"type":"string","nullable":true,"example":"90.0000"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","supplierReturnId","goodsReceiptId","goodsReceiptLineId","purchaseOrderLineId","receiptLineDescription","storeId","storeLocationId","storeLocationCode","stockItemId","stockItemCode","stockItemName","baseUnit","quantity","notes","sortOrder","receivedQuantity","previouslyReturnedQuantity","returnableQuantity","createdAt","updatedAt"]},"CreateSupplierReturnLineDto":{"type":"object","properties":{"goodsReceiptLineId":{"type":"string","description":"A line of the return's own goods receipt that moved stock.","format":"uuid"},"storeLocationId":{"type":"string","description":"The bin inside the return's store the goods are taken from. Omit for the\nstore's unbinned stock. Never transit.","format":"uuid"},"quantity":{"type":"string","example":"8.0000"},"notes":{"type":"string","maxLength":500,"example":"Bags torn on delivery"},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}},"required":["goodsReceiptLineId","quantity"]},"UpdateSupplierReturnLineDto":{"type":"object","properties":{"quantity":{"type":"string","example":"6.0000"},"storeLocationId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":500},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}}},"CreateSupplierReturnDto":{"type":"object","properties":{"goodsReceiptId":{"type":"string","description":"The POSTED goods receipt the goods arrived on, of the project in the path.","format":"uuid"},"storeId":{"type":"string","description":"The store the goods leave from: central, or this project's own site.","format":"uuid"},"reason":{"type":"string","maxLength":1000,"example":"Wrong grade delivered"},"supplierReference":{"type":"string","description":"The supplier's return authorisation or collection note number.","maxLength":100,"example":"RMA-4471"},"notes":{"type":"string","maxLength":2000},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateSupplierReturnLineDto"}}},"required":["goodsReceiptId","storeId","reason"]},"GoodsReceiptReturnableLineDto":{"type":"object","properties":{"goodsReceiptLineId":{"type":"string","format":"uuid"},"purchaseOrderLineId":{"type":"string","format":"uuid"},"description":{"type":"string"},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string"},"stockItemName":{"type":"string"},"baseUnit":{"type":"string"},"receivedQuantity":{"type":"string","example":"100.0000"},"returnedQuantity":{"type":"string","example":"10.0000","description":"Sum of POSTED supplier return lines."},"returnableQuantity":{"type":"string","example":"90.0000"}},"required":["goodsReceiptLineId","purchaseOrderLineId","description","stockItemId","stockItemCode","stockItemName","baseUnit","receivedQuantity","returnedQuantity","returnableQuantity"]},"CreateSupplierInvoiceLineDto":{"type":"object","properties":{"purchaseOrderLineId":{"type":"string","description":"An item on this invoice's own purchase order.","format":"uuid"},"quantity":{"type":"string","example":"40"},"unitPrice":{"type":"string","description":"The price on the supplier's invoice. Defaults to the order's price.","example":"38500.00"},"description":{"type":"string","description":"Defaults to the order line's description.","maxLength":2000},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}},"required":["purchaseOrderLineId","quantity"]},"CreateSupplierInvoiceDto":{"type":"object","properties":{"purchaseOrderId":{"type":"string","description":"An ISSUED or CLOSED purchase order.","format":"uuid"},"supplierInvoiceNumber":{"type":"string","description":"The number printed on the supplier's invoice. Spaces are removed and\nletters upper-cased, so the same invoice keyed twice is caught however it\nwas typed — a second live invoice with this number from this supplier is\na 409.","example":"INV-2026-0042","maxLength":64},"invoiceDate":{"type":"string","description":"`YYYY-MM-DD`, as printed.","example":"2026-10-01"},"receivedDate":{"type":"string","description":"When it reached the firm.","example":"2026-10-04"},"dueDate":{"type":"string","description":"Defaults to the invoice date plus the supplier's payment terms; left\nempty when the supplier has none."},"taxAmount":{"type":"string","description":"Tax as printed on the invoice. Defaults to 0.","example":"277200.00"},"notes":{"type":"string","maxLength":2000},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateSupplierInvoiceLineDto"}}},"required":["purchaseOrderId","supplierInvoiceNumber","invoiceDate"]},"SupplierInvoiceLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"supplierInvoiceId":{"type":"string","format":"uuid"},"purchaseOrderLineId":{"type":"string","format":"uuid"},"description":{"type":"string"},"unit":{"type":"string","example":"bag"},"quantity":{"type":"string","example":"40.0000"},"unitPrice":{"type":"string","example":"38500.00"},"lineAmount":{"type":"string","example":"1540000.0000","description":"quantity × unitPrice, computed by the database."},"sortOrder":{"type":"number"},"orderedUnitPrice":{"type":"string","nullable":true,"description":"The order line’s price, for comparison."},"orderedQuantity":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","supplierInvoiceId","purchaseOrderLineId","description","unit","quantity","unitPrice","lineAmount","sortOrder","createdAt","updatedAt"]},"SupplierInvoiceWithLinesDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"supplierId":{"type":"string","format":"uuid"},"supplierCode":{"type":"string","nullable":true},"supplierName":{"type":"string","nullable":true},"sourceType":{"enum":["PURCHASE_ORDER","SUBCONTRACT_VALUATION"],"type":"string"},"purchaseOrderId":{"type":"string","nullable":true,"format":"uuid","description":"Set for PURCHASE_ORDER invoices."},"purchaseOrderNumber":{"type":"string","nullable":true},"subcontractValuationId":{"type":"string","nullable":true,"format":"uuid","description":"Set for SUBCONTRACT_VALUATION invoices: the certificate that raised it."},"invoiceNumber":{"type":"string","example":"INV-0001"},"supplierInvoiceNumber":{"type":"string","example":"INV-2026-0042"},"status":{"enum":["DRAFT","SUBMITTED","ON_HOLD","APPROVED","CANCELLED"],"type":"string"},"invoiceDate":{"type":"string","example":"2026-10-01"},"receivedDate":{"type":"string","nullable":true},"dueDate":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"subtotalAmount":{"type":"string","example":"1540000.0000","description":"Sum of line amounts."},"taxAmount":{"type":"string","example":"277200.00"},"totalAmount":{"type":"string","example":"1817200.0000","description":"Subtotal plus tax."},"lineCount":{"type":"number"},"payableAmount":{"type":"string","example":"1817200.00","description":"totalAmount rounded to money scale — what can be paid."},"paidAmount":{"type":"string","example":"0.00","description":"Allocations of POSTED payments."},"outstandingAmount":{"type":"string","example":"1817200.00"},"paymentStatus":{"nullable":true,"enum":["UNPAID","PARTIALLY_PAID","PAID"],"type":"string","description":"For APPROVED invoices only; null otherwise, since nothing is owed yet."},"overdue":{"type":"boolean","description":"APPROVED, not fully paid, and past its due date (today in the organization’s timezone)."},"notes":{"type":"string","nullable":true},"recordedByMembershipId":{"type":"string","format":"uuid"},"recordedByName":{"type":"string","nullable":true},"submittedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"submittedAt":{"format":"date-time","type":"string","nullable":true},"approvedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"approvedByName":{"type":"string","nullable":true},"approvedAt":{"format":"date-time","type":"string","nullable":true},"matchStatus":{"nullable":true,"enum":["MATCHED","WITHIN_TOLERANCE","EXCEPTION"],"type":"string","description":"Recorded at approval. Use the match route before then."},"varianceReason":{"type":"string","nullable":true},"heldByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"heldAt":{"format":"date-time","type":"string","nullable":true},"holdReason":{"type":"string","nullable":true},"cancelledByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/SupplierInvoiceLineDto"}}},"required":["id","organizationId","projectId","supplierId","sourceType","invoiceNumber","supplierInvoiceNumber","status","invoiceDate","subtotalAmount","taxAmount","totalAmount","lineCount","payableAmount","paidAmount","outstandingAmount","overdue","recordedByMembershipId","createdAt","updatedAt","lines"]},"SupplierInvoiceDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"supplierId":{"type":"string","format":"uuid"},"supplierCode":{"type":"string","nullable":true},"supplierName":{"type":"string","nullable":true},"sourceType":{"enum":["PURCHASE_ORDER","SUBCONTRACT_VALUATION"],"type":"string"},"purchaseOrderId":{"type":"string","nullable":true,"format":"uuid","description":"Set for PURCHASE_ORDER invoices."},"purchaseOrderNumber":{"type":"string","nullable":true},"subcontractValuationId":{"type":"string","nullable":true,"format":"uuid","description":"Set for SUBCONTRACT_VALUATION invoices: the certificate that raised it."},"invoiceNumber":{"type":"string","example":"INV-0001"},"supplierInvoiceNumber":{"type":"string","example":"INV-2026-0042"},"status":{"enum":["DRAFT","SUBMITTED","ON_HOLD","APPROVED","CANCELLED"],"type":"string"},"invoiceDate":{"type":"string","example":"2026-10-01"},"receivedDate":{"type":"string","nullable":true},"dueDate":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"subtotalAmount":{"type":"string","example":"1540000.0000","description":"Sum of line amounts."},"taxAmount":{"type":"string","example":"277200.00"},"totalAmount":{"type":"string","example":"1817200.0000","description":"Subtotal plus tax."},"lineCount":{"type":"number"},"payableAmount":{"type":"string","example":"1817200.00","description":"totalAmount rounded to money scale — what can be paid."},"paidAmount":{"type":"string","example":"0.00","description":"Allocations of POSTED payments."},"outstandingAmount":{"type":"string","example":"1817200.00"},"paymentStatus":{"nullable":true,"enum":["UNPAID","PARTIALLY_PAID","PAID"],"type":"string","description":"For APPROVED invoices only; null otherwise, since nothing is owed yet."},"overdue":{"type":"boolean","description":"APPROVED, not fully paid, and past its due date (today in the organization’s timezone)."},"notes":{"type":"string","nullable":true},"recordedByMembershipId":{"type":"string","format":"uuid"},"recordedByName":{"type":"string","nullable":true},"submittedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"submittedAt":{"format":"date-time","type":"string","nullable":true},"approvedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"approvedByName":{"type":"string","nullable":true},"approvedAt":{"format":"date-time","type":"string","nullable":true},"matchStatus":{"nullable":true,"enum":["MATCHED","WITHIN_TOLERANCE","EXCEPTION"],"type":"string","description":"Recorded at approval. Use the match route before then."},"varianceReason":{"type":"string","nullable":true},"heldByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"heldAt":{"format":"date-time","type":"string","nullable":true},"holdReason":{"type":"string","nullable":true},"cancelledByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","supplierId","sourceType","invoiceNumber","supplierInvoiceNumber","status","invoiceDate","subtotalAmount","taxAmount","totalAmount","lineCount","payableAmount","paidAmount","outstandingAmount","overdue","recordedByMembershipId","createdAt","updatedAt"]},"UpdateSupplierInvoiceDto":{"type":"object","properties":{"supplierInvoiceNumber":{"type":"string","maxLength":64},"invoiceDate":{"type":"string"},"receivedDate":{"type":"string"},"dueDate":{"type":"string"},"taxAmount":{"type":"string"},"notes":{"type":"string","maxLength":2000}}},"UpdateSupplierInvoiceLineDto":{"type":"object","properties":{"quantity":{"type":"string"},"unitPrice":{"type":"string"},"description":{"type":"string","maxLength":2000},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}}},"InvoiceMatchLineDto":{"type":"object","properties":{"supplierInvoiceLineId":{"type":"string","format":"uuid"},"purchaseOrderLineId":{"type":"string","format":"uuid"},"description":{"type":"string"},"unit":{"type":"string"},"orderedQuantity":{"type":"string","example":"100.0000"},"receivedQuantity":{"type":"string","example":"60.0000","description":"Posted receipts less posted supplier returns."},"previouslyInvoicedQuantity":{"type":"string","example":"20.0000","description":"Claimed by this order line’s other submitted, held or approved invoices."},"invoicedQuantity":{"type":"string","example":"40.0000"},"quantityVariance":{"type":"string","example":"0.0000","description":"invoiced + previously invoiced − received. Positive is a claim for goods not received."},"orderedUnitPrice":{"type":"string","example":"38500.00"},"invoicedUnitPrice":{"type":"string","example":"39000.00"},"unitPriceVariance":{"type":"string","example":"500.00","description":"invoiced − ordered price."},"priceVarianceAmount":{"type":"string","example":"20000.0000","description":"unitPriceVariance × invoicedQuantity."},"priceWithinTolerance":{"type":"boolean","description":"Whether any price variance is inside tolerance."},"matchStatus":{"enum":["MATCHED","WITHIN_TOLERANCE","EXCEPTION"],"type":"string"},"exceptions":{"type":"array","items":{"type":"string","enum":["QUANTITY_EXCEEDS_RECEIPT","PRICE_VARIANCE"]}}},"required":["supplierInvoiceLineId","purchaseOrderLineId","description","unit","orderedQuantity","receivedQuantity","previouslyInvoicedQuantity","invoicedQuantity","quantityVariance","orderedUnitPrice","invoicedUnitPrice","unitPriceVariance","priceVarianceAmount","priceWithinTolerance","matchStatus","exceptions"]},"InvoiceMatchDto":{"type":"object","properties":{"supplierInvoiceId":{"type":"string","format":"uuid"},"matchStatus":{"enum":["MATCHED","WITHIN_TOLERANCE","EXCEPTION"],"type":"string","description":"The worst of the lines. An invoice with no lines is an EXCEPTION — there is nothing to match."},"snapshot":{"type":"boolean","description":"True when this is the snapshot recorded at approval rather than a live computation."},"priceTolerancePercent":{"type":"string","example":"0.00"},"amountTolerance":{"type":"string","example":"0.00"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceMatchLineDto"}}},"required":["supplierInvoiceId","matchStatus","snapshot","priceTolerancePercent","amountTolerance","lines"]},"ApproveSupplierInvoiceVarianceDto":{"type":"object","properties":{"varianceReason":{"type":"string","example":"Supplier delivered the balance direct to site; GRN to follow","maxLength":1000}},"required":["varianceReason"]},"SupplierInvoiceReasonDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000}},"required":["reason"]},"PurchaseOrderInvoicingLineDto":{"type":"object","properties":{"purchaseOrderLineId":{"type":"string","format":"uuid"},"description":{"type":"string"},"unit":{"type":"string"},"orderedQuantity":{"type":"string"},"receivedQuantity":{"type":"string","description":"Posted receipts less posted supplier returns."},"invoicedQuantity":{"type":"string","description":"On APPROVED invoices."},"pendingQuantity":{"type":"string","description":"On SUBMITTED or ON_HOLD invoices."},"invoiceableQuantity":{"type":"string","description":"received − invoiced − pending, floored at 0: what may still be invoiced without an exception."},"invoicedAmount":{"type":"string","description":"On APPROVED invoices, net of tax."}},"required":["purchaseOrderLineId","description","unit","orderedQuantity","receivedQuantity","invoicedQuantity","pendingQuantity","invoiceableQuantity","invoicedAmount"]},"PurchaseOrderInvoicingDto":{"type":"object","properties":{"purchaseOrderId":{"type":"string","format":"uuid"},"fullyInvoiced":{"type":"boolean","description":"Every line invoiced (approved) up to its ordered quantity — the order has nothing left to bill."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderInvoicingLineDto"}}},"required":["purchaseOrderId","fullyInvoiced","lines"]},"ProcurementSettingsDto":{"type":"object","properties":{"priceTolerancePercent":{"type":"string","example":"0.00"},"amountTolerance":{"type":"string","example":"0.00"},"customized":{"type":"boolean","description":"False until the organization changes a setting; the zero-tolerance defaults apply."}},"required":["priceTolerancePercent","amountTolerance","customized"]},"UpdateProcurementSettingsDto":{"type":"object","properties":{"priceTolerancePercent":{"type":"string","description":"How far an invoice price may differ from the order's, as a percentage of\nthe order price, before it is an exception.","example":"2.50"},"amountTolerance":{"type":"string","description":"A line's price variance amount below which it is tolerated regardless of\npercentage — for rounding on small lines.","example":"5000.00"}}},"CreateSupplierPaymentAllocationDto":{"type":"object","properties":{"supplierInvoiceId":{"type":"string","description":"An APPROVED invoice of the payment's supplier.","format":"uuid"},"amount":{"type":"string","example":"1817200.00"}},"required":["supplierInvoiceId","amount"]},"CreateSupplierPaymentDto":{"type":"object","properties":{"supplierId":{"type":"string","format":"uuid"},"paymentDate":{"type":"string","description":"The date the money left the firm.","example":"2026-10-15"},"method":{"type":"string","enum":["BANK_TRANSFER","CHEQUE","CASH","MOBILE_MONEY"]},"reference":{"type":"string","description":"Bank reference, cheque or receipt number.","example":"FT2628800123","maxLength":100},"supplierBankAccountId":{"type":"string","description":"Required for BANK_TRANSFER: a VERIFIED account of this supplier. Checked\nagain at posting.","format":"uuid"},"amount":{"type":"string","example":"1817200.00"},"currency":{"type":"string","description":"ISO 4217. Every allocated invoice must be in this currency."},"notes":{"type":"string","maxLength":2000},"allocations":{"type":"array","items":{"$ref":"#/components/schemas/CreateSupplierPaymentAllocationDto"}}},"required":["supplierId","paymentDate","method","amount"]},"SupplierPaymentAllocationDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"supplierPaymentId":{"type":"string","format":"uuid"},"supplierInvoiceId":{"type":"string","format":"uuid"},"invoiceNumber":{"type":"string","example":"INV-0004"},"supplierInvoiceNumber":{"type":"string","example":"ACME-778"},"projectId":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"1817200.00"},"invoicePayableAmount":{"type":"string","example":"1817200.00","description":"The invoice total rounded to money scale."},"invoiceOutstandingAmount":{"type":"string","example":"0.00","description":"What the invoice still owes after every POSTED payment — this one included once it is posted."},"createdAt":{"format":"date-time","type":"string"}},"required":["id","supplierPaymentId","supplierInvoiceId","invoiceNumber","supplierInvoiceNumber","projectId","amount","invoicePayableAmount","invoiceOutstandingAmount","createdAt"]},"SupplierPaymentWithAllocationsDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"supplierId":{"type":"string","format":"uuid"},"supplierCode":{"type":"string","nullable":true},"supplierName":{"type":"string","nullable":true},"paymentNumber":{"type":"string","example":"PAY-0001"},"status":{"enum":["DRAFT","POSTED","VOIDED"],"type":"string"},"paymentDate":{"type":"string","example":"2026-10-15"},"method":{"enum":["BANK_TRANSFER","CHEQUE","CASH","MOBILE_MONEY"],"type":"string"},"reference":{"type":"string","nullable":true},"supplierBankAccountId":{"type":"string","nullable":true,"format":"uuid"},"amount":{"type":"string","example":"1817200.00"},"allocatedAmount":{"type":"string","example":"1817200.00","description":"Sum of allocations. Must equal `amount` to post."},"allocationCount":{"type":"number"},"currency":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"recordedByMembershipId":{"type":"string","format":"uuid"},"recordedByName":{"type":"string","nullable":true},"postedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"postedByName":{"type":"string","nullable":true},"postedAt":{"format":"date-time","type":"string","nullable":true},"voidedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"voidedAt":{"format":"date-time","type":"string","nullable":true},"voidReason":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"allocations":{"type":"array","items":{"$ref":"#/components/schemas/SupplierPaymentAllocationDto"}}},"required":["id","organizationId","supplierId","paymentNumber","status","paymentDate","method","amount","allocatedAmount","allocationCount","recordedByMembershipId","createdAt","updatedAt","allocations"]},"SupplierPaymentDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"supplierId":{"type":"string","format":"uuid"},"supplierCode":{"type":"string","nullable":true},"supplierName":{"type":"string","nullable":true},"paymentNumber":{"type":"string","example":"PAY-0001"},"status":{"enum":["DRAFT","POSTED","VOIDED"],"type":"string"},"paymentDate":{"type":"string","example":"2026-10-15"},"method":{"enum":["BANK_TRANSFER","CHEQUE","CASH","MOBILE_MONEY"],"type":"string"},"reference":{"type":"string","nullable":true},"supplierBankAccountId":{"type":"string","nullable":true,"format":"uuid"},"amount":{"type":"string","example":"1817200.00"},"allocatedAmount":{"type":"string","example":"1817200.00","description":"Sum of allocations. Must equal `amount` to post."},"allocationCount":{"type":"number"},"currency":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"recordedByMembershipId":{"type":"string","format":"uuid"},"recordedByName":{"type":"string","nullable":true},"postedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"postedByName":{"type":"string","nullable":true},"postedAt":{"format":"date-time","type":"string","nullable":true},"voidedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"voidedAt":{"format":"date-time","type":"string","nullable":true},"voidReason":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","supplierId","paymentNumber","status","paymentDate","method","amount","allocatedAmount","allocationCount","recordedByMembershipId","createdAt","updatedAt"]},"UpdateSupplierPaymentDto":{"type":"object","properties":{"paymentDate":{"type":"string"},"method":{"type":"string","enum":["BANK_TRANSFER","CHEQUE","CASH","MOBILE_MONEY"]},"reference":{"type":"string","maxLength":100},"supplierBankAccountId":{"type":"string","format":"uuid"},"amount":{"type":"string"},"currency":{"type":"string"},"notes":{"type":"string","maxLength":2000}}},"UpdateSupplierPaymentAllocationDto":{"type":"object","properties":{"amount":{"type":"string"}},"required":["amount"]},"VoidSupplierPaymentDto":{"type":"object","properties":{"reason":{"type":"string","example":"Transfer recalled by the bank — wrong beneficiary branch","maxLength":1000}},"required":["reason"]},"CurrencyBalanceDto":{"type":"object","properties":{"currency":{"type":"string","nullable":true},"balance":{"type":"string","example":"0.00"}},"required":["balance"]},"SupplierStatementEntryDto":{"type":"object","properties":{"date":{"type":"string","example":"2026-10-01"},"type":{"enum":["INVOICE","PAYMENT"],"type":"string"},"documentId":{"type":"string","format":"uuid"},"reference":{"type":"string","example":"INV-0004","description":"The firm’s number."},"externalReference":{"type":"string","nullable":true,"description":"The supplier’s invoice number, or the bank reference."},"currency":{"type":"string","nullable":true},"debit":{"type":"string","example":"1817200.00","description":"Owed: approved invoices."},"credit":{"type":"string","example":"0.00","description":"Paid: posted payments."},"balance":{"type":"string","example":"1817200.00","description":"Running balance in this entry’s currency."}},"required":["date","type","documentId","reference","debit","credit","balance"]},"SupplierStatementDto":{"type":"object","properties":{"supplierId":{"type":"string","format":"uuid"},"from":{"type":"string","nullable":true},"to":{"type":"string","nullable":true},"openingBalances":{"description":"Balance brought forward from before `from`, per currency.","type":"array","items":{"$ref":"#/components/schemas/CurrencyBalanceDto"}},"entries":{"type":"array","items":{"$ref":"#/components/schemas/SupplierStatementEntryDto"}},"closingBalances":{"type":"array","items":{"$ref":"#/components/schemas/CurrencyBalanceDto"}}},"required":["supplierId","openingBalances","entries","closingBalances"]},"PayablesAgingRowDto":{"type":"object","properties":{"supplierId":{"type":"string","format":"uuid"},"supplierCode":{"type":"string"},"supplierName":{"type":"string"},"currency":{"type":"string","nullable":true},"current":{"type":"string","example":"0.00","description":"Not yet due, or with no due date."},"days1To30":{"type":"string","example":"0.00"},"days31To60":{"type":"string","example":"0.00"},"days61To90":{"type":"string","example":"0.00"},"over90":{"type":"string","example":"0.00"},"total":{"type":"string","example":"0.00"},"invoiceCount":{"type":"number"}},"required":["supplierId","supplierCode","supplierName","current","days1To30","days31To60","days61To90","over90","total","invoiceCount"]},"PayablesAgingTotalDto":{"type":"object","properties":{"currency":{"type":"string","nullable":true},"current":{"type":"string"},"days1To30":{"type":"string"},"days31To60":{"type":"string"},"days61To90":{"type":"string"},"over90":{"type":"string"},"total":{"type":"string"}},"required":["current","days1To30","days31To60","days61To90","over90","total"]},"PayablesAgingDto":{"type":"object","properties":{"asOf":{"type":"string","example":"2026-10-31"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/PayablesAgingRowDto"}},"totals":{"type":"array","items":{"$ref":"#/components/schemas/PayablesAgingTotalDto"}}},"required":["asOf","rows","totals"]},"CreateRfqLineDto":{"type":"object","properties":{"requisitionLineId":{"type":"string","description":"A line of the RFQ's own requisition.","format":"uuid"},"quantity":{"type":"string","description":"Defaults to the requisition line's quantity; may be less, never more.","example":"500"}},"required":["requisitionLineId"]},"CreateRfqDto":{"type":"object","properties":{"requisitionId":{"type":"string","format":"uuid"},"title":{"type":"string","example":"Cement and reinforcement for Block B slab","maxLength":200},"closingDate":{"type":"string","description":"The date suppliers are asked to quote by.","example":"2026-10-20"},"notes":{"type":"string","maxLength":2000},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateRfqLineDto"}},"supplierIds":{"description":"ACTIVE suppliers to invite.","type":"array","items":{"type":"string","format":"uuid"}}},"required":["requisitionId","title"]},"RfqLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"requisitionLineId":{"type":"string","format":"uuid"},"description":{"type":"string"},"unit":{"type":"string"},"quantity":{"type":"string","example":"500.0000"},"requisitionQuantity":{"type":"string","example":"500.0000"},"sortOrder":{"type":"number"},"awardedQuotationId":{"type":"string","nullable":true,"format":"uuid"}},"required":["id","requisitionLineId","description","unit","quantity","requisitionQuantity","sortOrder"]},"RfqSupplierDto":{"type":"object","properties":{"supplierId":{"type":"string","format":"uuid"},"supplierCode":{"type":"string"},"supplierName":{"type":"string"},"quotationId":{"type":"string","nullable":true,"format":"uuid","description":"Their live quotation, once recorded."},"quotationStatus":{"nullable":true,"enum":["RECEIVED","WITHDRAWN","AWARDED","NOT_AWARDED"],"type":"string"}},"required":["supplierId","supplierCode","supplierName"]},"RfqDetailDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"requisitionId":{"type":"string","format":"uuid"},"requisitionNumber":{"type":"string","nullable":true},"rfqNumber":{"type":"string","example":"RFQ-0001"},"title":{"type":"string"},"status":{"enum":["DRAFT","ISSUED","CLOSED","AWARDED","CANCELLED"],"type":"string"},"closingDate":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"lineCount":{"type":"number"},"supplierCount":{"type":"number"},"quotationCount":{"type":"number","description":"Live (not withdrawn) quotations."},"createdByMembershipId":{"type":"string","format":"uuid"},"issuedAt":{"format":"date-time","type":"string","nullable":true},"closedAt":{"format":"date-time","type":"string","nullable":true},"awardedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"awardedAt":{"format":"date-time","type":"string","nullable":true},"awardReason":{"type":"string","nullable":true},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/RfqLineDto"}},"suppliers":{"type":"array","items":{"$ref":"#/components/schemas/RfqSupplierDto"}}},"required":["id","organizationId","projectId","requisitionId","rfqNumber","title","status","lineCount","supplierCount","quotationCount","createdByMembershipId","createdAt","updatedAt","lines","suppliers"]},"RfqDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"requisitionId":{"type":"string","format":"uuid"},"requisitionNumber":{"type":"string","nullable":true},"rfqNumber":{"type":"string","example":"RFQ-0001"},"title":{"type":"string"},"status":{"enum":["DRAFT","ISSUED","CLOSED","AWARDED","CANCELLED"],"type":"string"},"closingDate":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"lineCount":{"type":"number"},"supplierCount":{"type":"number"},"quotationCount":{"type":"number","description":"Live (not withdrawn) quotations."},"createdByMembershipId":{"type":"string","format":"uuid"},"issuedAt":{"format":"date-time","type":"string","nullable":true},"closedAt":{"format":"date-time","type":"string","nullable":true},"awardedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"awardedAt":{"format":"date-time","type":"string","nullable":true},"awardReason":{"type":"string","nullable":true},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","requisitionId","rfqNumber","title","status","lineCount","supplierCount","quotationCount","createdByMembershipId","createdAt","updatedAt"]},"UpdateRfqDto":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"closingDate":{"type":"string"},"notes":{"type":"string","maxLength":2000}}},"UpdateRfqLineDto":{"type":"object","properties":{"quantity":{"type":"string"}},"required":["quantity"]},"InviteRfqSupplierDto":{"type":"object","properties":{"supplierId":{"type":"string","format":"uuid"}},"required":["supplierId"]},"RfqReasonDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000}},"required":["reason"]},"ComparisonQuoteDto":{"type":"object","properties":{"quotationId":{"type":"string","format":"uuid"},"supplierId":{"type":"string","format":"uuid"},"supplierName":{"type":"string"},"unitPrice":{"type":"string"},"quantityOffered":{"type":"string","nullable":true},"lineAmount":{"type":"string"},"lowest":{"type":"boolean","description":"The cheapest unit price among valid quotations for this line."},"expired":{"type":"boolean","description":"Past its validUntil date — cannot be awarded."},"awarded":{"type":"boolean"}},"required":["quotationId","supplierId","supplierName","unitPrice","lineAmount","lowest","expired","awarded"]},"ComparisonLineDto":{"type":"object","properties":{"rfqLineId":{"type":"string","format":"uuid"},"description":{"type":"string"},"unit":{"type":"string"},"quantity":{"type":"string"},"lowestUnitPrice":{"type":"string","nullable":true},"quotes":{"type":"array","items":{"$ref":"#/components/schemas/ComparisonQuoteDto"}}},"required":["rfqLineId","description","unit","quantity","quotes"]},"ComparisonQuotationDto":{"type":"object","properties":{"quotationId":{"type":"string","format":"uuid"},"supplierId":{"type":"string","format":"uuid"},"supplierName":{"type":"string"},"status":{"enum":["RECEIVED","WITHDRAWN","AWARDED","NOT_AWARDED"],"type":"string"},"totalAmount":{"type":"string"},"quotedLineCount":{"type":"number"},"complete":{"type":"boolean","description":"Quotes every line of the RFQ."},"lowestCompleteTotal":{"type":"boolean","description":"The cheapest total among valid quotations that quote every line."},"validUntil":{"type":"string","nullable":true},"expired":{"type":"boolean"},"deliveryLeadDays":{"type":"number","nullable":true},"paymentTermsDays":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true}},"required":["quotationId","supplierId","supplierName","status","totalAmount","quotedLineCount","complete","lowestCompleteTotal","expired"]},"RfqComparisonDto":{"type":"object","properties":{"rfqId":{"type":"string","format":"uuid"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ComparisonLineDto"}},"quotations":{"type":"array","items":{"$ref":"#/components/schemas/ComparisonQuotationDto"}}},"required":["rfqId","lines","quotations"]},"RfqAwardItemDto":{"type":"object","properties":{"rfqLineId":{"type":"string","format":"uuid"},"quotationId":{"type":"string","format":"uuid"}},"required":["rfqLineId","quotationId"]},"AwardRfqDto":{"type":"object","properties":{"awards":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/RfqAwardItemDto"}},"reason":{"type":"string","description":"Required when any line goes to a quotation that is not the cheapest valid\none for that line: lead time, quality, a supplier's track record.","maxLength":1000}},"required":["awards"]},"AwardedPurchaseOrderDto":{"type":"object","properties":{"purchaseOrderId":{"type":"string","format":"uuid"},"purchaseOrderNumber":{"type":"string","example":"PO-0007"},"supplierId":{"type":"string","format":"uuid"}},"required":["purchaseOrderId","purchaseOrderNumber","supplierId"]},"RfqAwardResultDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"requisitionId":{"type":"string","format":"uuid"},"requisitionNumber":{"type":"string","nullable":true},"rfqNumber":{"type":"string","example":"RFQ-0001"},"title":{"type":"string"},"status":{"enum":["DRAFT","ISSUED","CLOSED","AWARDED","CANCELLED"],"type":"string"},"closingDate":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"lineCount":{"type":"number"},"supplierCount":{"type":"number"},"quotationCount":{"type":"number","description":"Live (not withdrawn) quotations."},"createdByMembershipId":{"type":"string","format":"uuid"},"issuedAt":{"format":"date-time","type":"string","nullable":true},"closedAt":{"format":"date-time","type":"string","nullable":true},"awardedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"awardedAt":{"format":"date-time","type":"string","nullable":true},"awardReason":{"type":"string","nullable":true},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/RfqLineDto"}},"suppliers":{"type":"array","items":{"$ref":"#/components/schemas/RfqSupplierDto"}},"purchaseOrders":{"description":"One DRAFT order per awarded supplier, to be reviewed and issued.","type":"array","items":{"$ref":"#/components/schemas/AwardedPurchaseOrderDto"}}},"required":["id","organizationId","projectId","requisitionId","rfqNumber","title","status","lineCount","supplierCount","quotationCount","createdByMembershipId","createdAt","updatedAt","lines","suppliers","purchaseOrders"]},"QuotationDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"rfqId":{"type":"string","format":"uuid"},"supplierId":{"type":"string","format":"uuid"},"supplierCode":{"type":"string","nullable":true},"supplierName":{"type":"string","nullable":true},"quotationNumber":{"type":"string","example":"QTN-0001"},"supplierReference":{"type":"string","nullable":true},"status":{"enum":["RECEIVED","WITHDRAWN","AWARDED","NOT_AWARDED"],"type":"string"},"receivedDate":{"type":"string"},"validUntil":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"deliveryLeadDays":{"type":"number","nullable":true},"paymentTermsDays":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true},"totalAmount":{"type":"string","example":"18900000.0000"},"quotedLineCount":{"type":"number"},"withdrawnAt":{"format":"date-time","type":"string","nullable":true},"withdrawalReason":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","rfqId","supplierId","quotationNumber","status","receivedDate","totalAmount","quotedLineCount","createdAt","updatedAt"]},"QuotationLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"rfqLineId":{"type":"string","format":"uuid"},"description":{"type":"string"},"unit":{"type":"string"},"requestedQuantity":{"type":"string","example":"500.0000","description":"What the RFQ asked for."},"unitPrice":{"type":"string","example":"37800.00"},"quantityOffered":{"type":"string","nullable":true},"lineAmount":{"type":"string","example":"18900000.0000","description":"unitPrice × (quantityOffered or the requested quantity)."},"notes":{"type":"string","nullable":true}},"required":["id","rfqLineId","description","unit","requestedQuantity","unitPrice","lineAmount"]},"QuotationWithLinesDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"rfqId":{"type":"string","format":"uuid"},"supplierId":{"type":"string","format":"uuid"},"supplierCode":{"type":"string","nullable":true},"supplierName":{"type":"string","nullable":true},"quotationNumber":{"type":"string","example":"QTN-0001"},"supplierReference":{"type":"string","nullable":true},"status":{"enum":["RECEIVED","WITHDRAWN","AWARDED","NOT_AWARDED"],"type":"string"},"receivedDate":{"type":"string"},"validUntil":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"deliveryLeadDays":{"type":"number","nullable":true},"paymentTermsDays":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true},"totalAmount":{"type":"string","example":"18900000.0000"},"quotedLineCount":{"type":"number"},"withdrawnAt":{"format":"date-time","type":"string","nullable":true},"withdrawalReason":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/QuotationLineDto"}}},"required":["id","rfqId","supplierId","quotationNumber","status","receivedDate","totalAmount","quotedLineCount","createdAt","updatedAt","lines"]},"QuotationLineInputDto":{"type":"object","properties":{"rfqLineId":{"type":"string","format":"uuid"},"unitPrice":{"type":"string","example":"37800.00"},"quantityOffered":{"type":"string","description":"Only when the supplier offers less than the requested quantity."},"notes":{"type":"string","maxLength":500}},"required":["rfqLineId","unitPrice"]},"CreateQuotationDto":{"type":"object","properties":{"supplierId":{"type":"string","format":"uuid"},"receivedDate":{"type":"string","example":"2026-10-12"},"lines":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/QuotationLineInputDto"}},"supplierReference":{"type":"string","description":"The supplier's own reference.","example":"Q-2026-118","maxLength":64},"validUntil":{"type":"string","description":"After this date the offer lapses and cannot be awarded."},"currency":{"type":"string"},"deliveryLeadDays":{"type":"number","minimum":0,"maximum":3650},"paymentTermsDays":{"type":"number","minimum":0,"maximum":365},"notes":{"type":"string","maxLength":2000}},"required":["supplierId","receivedDate","lines"]},"UpdateQuotationDto":{"type":"object","properties":{"receivedDate":{"type":"string"},"lines":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/QuotationLineInputDto"}},"supplierReference":{"type":"string","description":"The supplier's own reference.","example":"Q-2026-118","maxLength":64},"validUntil":{"type":"string","description":"After this date the offer lapses and cannot be awarded."},"currency":{"type":"string"},"deliveryLeadDays":{"type":"number","minimum":0,"maximum":3650},"paymentTermsDays":{"type":"number","minimum":0,"maximum":365},"notes":{"type":"string","maxLength":2000}}},"WithdrawQuotationDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000}},"required":["reason"]},"SubcontractItemInputDto":{"type":"object","properties":{"budgetLineId":{"type":"string","description":"A budget line of the subcontract's project.","format":"uuid"},"description":{"type":"string","example":"Blockwork, 200mm, ground floor","maxLength":2000},"unit":{"type":"string","example":"m2","maxLength":16},"quantity":{"type":"string","example":"1200"},"rate":{"type":"string","example":"45000.00"}},"required":["budgetLineId","description","unit","quantity","rate"]},"CreateSubcontractDto":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"supplierId":{"type":"string","format":"uuid"},"title":{"type":"string","example":"Blockwork and plastering, Block B","maxLength":200},"items":{"type":"array","items":{"$ref":"#/components/schemas/SubcontractItemInputDto"}},"scope":{"type":"string","maxLength":4000},"startDate":{"type":"string"},"endDate":{"type":"string"},"currency":{"type":"string"},"retentionPercent":{"type":"string","description":"Withheld from each certificate, 0–20. Defaults to 5.","example":"5"},"retentionLimitPercent":{"type":"string","description":"Retention stops at this % of the contract sum.","example":"5"},"defectsPeriodDays":{"type":"number","description":"Defaults to 365.","minimum":0,"maximum":3650}},"required":["projectId","supplierId","title"]},"SubcontractItemDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"budgetLineId":{"type":"string","format":"uuid"},"variationId":{"type":"string","nullable":true,"format":"uuid"},"description":{"type":"string"},"unit":{"type":"string"},"quantity":{"type":"string","example":"1200.0000"},"rate":{"type":"string","example":"45000.00"},"amount":{"type":"string","example":"54000000.0000"},"certifiedQuantity":{"type":"string","example":"300.0000","description":"Cumulative quantity in the latest certified valuation."},"sortOrder":{"type":"number"}},"required":["id","budgetLineId","description","unit","quantity","rate","amount","certifiedQuantity","sortOrder"]},"SubcontractDetailDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"supplierId":{"type":"string","format":"uuid"},"supplierCode":{"type":"string","nullable":true},"supplierName":{"type":"string","nullable":true},"subcontractNumber":{"type":"string","example":"SC-0001"},"title":{"type":"string"},"scope":{"type":"string","nullable":true},"status":{"enum":["DRAFT","ACTIVE","PRACTICALLY_COMPLETE","FINAL_ACCOUNT_CLOSED","TERMINATED"],"type":"string"},"startDate":{"type":"string","nullable":true},"endDate":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"retentionPercent":{"type":"string","example":"5.00"},"retentionLimitPercent":{"type":"string","nullable":true},"defectsPeriodDays":{"type":"number"},"originalContractSum":{"type":"string","nullable":true,"description":"The schedule total when activated."},"contractSum":{"type":"string","example":"56400000.0000","description":"The schedule total now — original plus approved variations."},"certifiedToDate":{"type":"string","example":"18000000.00","description":"Gross value in the latest certified valuation."},"retentionHeld":{"type":"string","example":"900000.00","description":"Retention held in the latest certified valuation."},"practicalCompletionDate":{"type":"string","nullable":true},"activatedAt":{"format":"date-time","type":"string","nullable":true},"finalAccountClosedAt":{"format":"date-time","type":"string","nullable":true},"terminatedAt":{"format":"date-time","type":"string","nullable":true},"terminationReason":{"type":"string","nullable":true},"createdByMembershipId":{"type":"string","format":"uuid"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SubcontractItemDto"}}},"required":["id","organizationId","projectId","supplierId","subcontractNumber","title","status","retentionPercent","defectsPeriodDays","contractSum","certifiedToDate","retentionHeld","createdByMembershipId","createdAt","updatedAt","items"]},"SubcontractDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"supplierId":{"type":"string","format":"uuid"},"supplierCode":{"type":"string","nullable":true},"supplierName":{"type":"string","nullable":true},"subcontractNumber":{"type":"string","example":"SC-0001"},"title":{"type":"string"},"scope":{"type":"string","nullable":true},"status":{"enum":["DRAFT","ACTIVE","PRACTICALLY_COMPLETE","FINAL_ACCOUNT_CLOSED","TERMINATED"],"type":"string"},"startDate":{"type":"string","nullable":true},"endDate":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"retentionPercent":{"type":"string","example":"5.00"},"retentionLimitPercent":{"type":"string","nullable":true},"defectsPeriodDays":{"type":"number"},"originalContractSum":{"type":"string","nullable":true,"description":"The schedule total when activated."},"contractSum":{"type":"string","example":"56400000.0000","description":"The schedule total now — original plus approved variations."},"certifiedToDate":{"type":"string","example":"18000000.00","description":"Gross value in the latest certified valuation."},"retentionHeld":{"type":"string","example":"900000.00","description":"Retention held in the latest certified valuation."},"practicalCompletionDate":{"type":"string","nullable":true},"activatedAt":{"format":"date-time","type":"string","nullable":true},"finalAccountClosedAt":{"format":"date-time","type":"string","nullable":true},"terminatedAt":{"format":"date-time","type":"string","nullable":true},"terminationReason":{"type":"string","nullable":true},"createdByMembershipId":{"type":"string","format":"uuid"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","projectId","supplierId","subcontractNumber","title","status","retentionPercent","defectsPeriodDays","contractSum","certifiedToDate","retentionHeld","createdByMembershipId","createdAt","updatedAt"]},"UpdateSubcontractDto":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"scope":{"type":"string","maxLength":4000},"startDate":{"type":"string"},"endDate":{"type":"string"},"currency":{"type":"string"},"retentionPercent":{"type":"string","description":"Withheld from each certificate, 0–20. Defaults to 5.","example":"5"},"retentionLimitPercent":{"type":"string","description":"Retention stops at this % of the contract sum.","example":"5"},"defectsPeriodDays":{"type":"number","description":"Defaults to 365.","minimum":0,"maximum":3650}}},"UpdateSubcontractItemDto":{"type":"object","properties":{"budgetLineId":{"type":"string","format":"uuid"},"description":{"type":"string","maxLength":2000},"unit":{"type":"string","maxLength":16},"quantity":{"type":"string"},"rate":{"type":"string"}}},"PracticalCompletionDto":{"type":"object","properties":{"practicalCompletionDate":{"type":"string","example":"2026-12-15"}},"required":["practicalCompletionDate"]},"SubcontractReasonDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000}},"required":["reason"]},"VariationLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"itemId":{"type":"string","nullable":true,"format":"uuid"},"quantityChange":{"type":"string","nullable":true},"description":{"type":"string","description":"The item’s description, or the new item’s."},"unit":{"type":"string"},"quantity":{"type":"string","nullable":true},"rate":{"type":"string"},"budgetLineId":{"type":"string","nullable":true,"format":"uuid"},"amount":{"type":"string","example":"5400000.0000","description":"Signed: (change or new quantity) × rate."}},"required":["id","description","unit","rate","amount"]},"VariationDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subcontractId":{"type":"string","format":"uuid"},"variationNumber":{"type":"number","example":1},"title":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"enum":["DRAFT","APPROVED","REJECTED"],"type":"string"},"amount":{"type":"string","example":"5400000.0000","description":"Signed total."},"raisedByMembershipId":{"type":"string","format":"uuid"},"decidedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"decidedAt":{"format":"date-time","type":"string","nullable":true},"decisionNote":{"type":"string","nullable":true},"lines":{"type":"array","items":{"$ref":"#/components/schemas/VariationLineDto"}},"createdAt":{"format":"date-time","type":"string"}},"required":["id","subcontractId","variationNumber","title","status","amount","raisedByMembershipId","lines","createdAt"]},"VariationLineInputDto":{"type":"object","properties":{"itemId":{"type":"string","format":"uuid"},"quantityChange":{"type":"string","description":"Signed and non-zero: `-50` omits fifty units.","example":"120"},"description":{"type":"string","maxLength":2000},"unit":{"type":"string","maxLength":16},"quantity":{"type":"string"},"rate":{"type":"string"},"budgetLineId":{"type":"string","format":"uuid"}}},"CreateVariationDto":{"type":"object","properties":{"title":{"type":"string","example":"Additional blockwork to plant room","maxLength":200},"description":{"type":"string","description":"The instruction or reason.","maxLength":2000},"lines":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/VariationLineInputDto"}}},"required":["title","lines"]},"DecideVariationDto":{"type":"object","properties":{"note":{"type":"string","maxLength":1000}}},"ValuationLineDto":{"type":"object","properties":{"itemId":{"type":"string","format":"uuid"},"description":{"type":"string"},"unit":{"type":"string"},"rate":{"type":"string"},"itemQuantity":{"type":"string","description":"The item’s quantity now."},"previousQuantity":{"type":"string","description":"Cumulative in the previous certificate."},"cumulativeQuantity":{"type":"string","description":"Cumulative in this valuation."},"valueToDate":{"type":"string","description":"cumulativeQuantity × rate."},"valueThisPeriod":{"type":"string","description":"This period’s movement, × rate."}},"required":["itemId","description","unit","rate","itemQuantity","previousQuantity","cumulativeQuantity","valueToDate","valueThisPeriod"]},"ValuationDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subcontractId":{"type":"string","format":"uuid"},"valuationNumber":{"type":"number","example":3},"periodEnd":{"type":"string","example":"2026-10-31"},"status":{"enum":["DRAFT","CERTIFIED","CANCELLED"],"type":"string"},"retentionReleasePercent":{"type":"string","example":"0.00"},"notes":{"type":"string","nullable":true},"certified":{"type":"boolean","description":"True when the figures are the certificate’s snapshot; false while a draft computes them live."},"grossToDate":{"type":"string","example":"18000000.00"},"retentionToDate":{"type":"string","example":"900000.00"},"netToDate":{"type":"string","example":"17100000.00"},"previouslyCertified":{"type":"string","example":"11400000.00"},"amountDue":{"type":"string","example":"5700000.00","description":"net to date − previously certified."},"preparedByMembershipId":{"type":"string","format":"uuid"},"certifiedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"certifiedAt":{"format":"date-time","type":"string","nullable":true},"supplierInvoiceId":{"type":"string","nullable":true,"format":"uuid","description":"The approved supplier invoice certification raised."},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ValuationLineDto"}},"createdAt":{"format":"date-time","type":"string"}},"required":["id","subcontractId","valuationNumber","periodEnd","status","retentionReleasePercent","certified","grossToDate","retentionToDate","netToDate","previouslyCertified","amountDue","preparedByMembershipId","lines","createdAt"]},"ValuationLineInputDto":{"type":"object","properties":{"itemId":{"type":"string","format":"uuid"},"cumulativeQuantity":{"type":"string","description":"Work done to date on the item — cumulative, never this period's increment."}},"required":["itemId","cumulativeQuantity"]},"CreateValuationDto":{"type":"object","properties":{"periodEnd":{"type":"string","example":"2026-10-31"},"retentionReleasePercent":{"type":"string","description":"Cumulative share of retention released to date, 0–100. Only once the\nsubcontract is practically complete; never less than last time."},"notes":{"type":"string","maxLength":2000},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ValuationLineInputDto"}}},"required":["periodEnd"]},"UpdateValuationDto":{"type":"object","properties":{"periodEnd":{"type":"string"},"retentionReleasePercent":{"type":"string"},"notes":{"type":"string","maxLength":2000},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ValuationLineInputDto"}}}},"SubcontractBudgetLineOptionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"description":{"type":"string","example":"Internal finishes — plaster and screed"},"costCentreCode":{"type":"string","nullable":true,"example":"CC-FIN"},"boqItemCode":{"type":"string","nullable":true,"example":"4.2.1"}},"required":["id","description","costCentreCode","boqItemCode"]},"SupplierMetricDto":{"type":"object","properties":{"value":{"type":"string","nullable":true,"example":"92.5","description":"A percentage to 1dp, or days to 1dp for lead time."},"sampleSize":{"type":"number","example":40,"description":"How many events the value is computed over."}},"required":["sampleSize"]},"SupplierSpendDto":{"type":"object","properties":{"currency":{"type":"string","nullable":true},"committed":{"type":"string","example":"125000000.0000","description":"Current commitment: issued and closed orders, live subcontract schedules."},"invoiced":{"type":"string","example":"98000000.0000","description":"Approved invoice lines, net of tax, plus subcontract work certified to date."},"paid":{"type":"string","example":"90000000.00","description":"Posted payments in the period."}},"required":["committed","invoiced","paid"]},"SupplierPerformanceDto":{"type":"object","properties":{"supplierId":{"type":"string","format":"uuid"},"supplierCode":{"type":"string"},"supplierName":{"type":"string"},"supplierType":{"enum":["MATERIALS","SERVICES","SUBCONTRACTOR","PLANT_HIRE","CONSULTANT"],"type":"string"},"status":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"from":{"type":"string","nullable":true},"to":{"type":"string","nullable":true},"onTimeDelivery":{"description":"Of order lines with an expected delivery date that is past or already met, the % fully received by that date.","allOf":[{"$ref":"#/components/schemas/SupplierMetricDto"}]},"fillRate":{"description":"For closed orders, value received (net of returns) as a % of value ordered.","allOf":[{"$ref":"#/components/schemas/SupplierMetricDto"}]},"returnRate":{"description":"Value returned as a % of value received.","allOf":[{"$ref":"#/components/schemas/SupplierMetricDto"}]},"invoiceExceptionRate":{"description":"Of order invoices approved or held, the % that were held or approved despite not matching.","allOf":[{"$ref":"#/components/schemas/SupplierMetricDto"}]},"averageLeadTimeDays":{"description":"Average days from an order’s issue to its first receipt.","allOf":[{"$ref":"#/components/schemas/SupplierMetricDto"}]},"quoteWinRate":{"description":"Of quotations decided by an award, the % that won.","allOf":[{"$ref":"#/components/schemas/SupplierMetricDto"}]},"spend":{"type":"array","items":{"$ref":"#/components/schemas/SupplierSpendDto"}}},"required":["supplierId","supplierCode","supplierName","supplierType","status","onTimeDelivery","fillRate","returnRate","invoiceExceptionRate","averageLeadTimeDays","quoteWinRate","spend"]},"CreateInventoryAdjustmentLineDto":{"type":"object","properties":{"stockItemId":{"type":"string","format":"uuid"},"storeLocationId":{"type":"string","description":"A bin inside the adjustment's store; omit for unbinned stock. Never transit.","format":"uuid"},"quantity":{"type":"string","description":"Positive, in the item's base unit. The reason decides the direction.","example":"2.0000"},"notes":{"type":"string","maxLength":500},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}},"required":["stockItemId","quantity"]},"CreateInventoryAdjustmentDto":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"reason":{"enum":["DAMAGED","SCRAPPED","FOUND"],"type":"string","description":"`DAMAGED` and `SCRAPPED` write stock off; `FOUND` brings it on. There is no loss or theft reason — unexplained shortages are found by a stock count."},"explanation":{"type":"string","maxLength":1000,"example":"Roof leak over bay C; 6 bags set solid"},"reference":{"type":"string","maxLength":100,"example":"DMG-2026-014"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateInventoryAdjustmentLineDto"}}},"required":["storeId","reason","explanation"]},"InventoryAdjustmentDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"storeCode":{"type":"string","nullable":true},"storeName":{"type":"string","nullable":true},"storeProjectId":{"type":"string","nullable":true,"format":"uuid","description":"The store’s project — NULL for a central store."},"inventoryAdjustmentNumber":{"type":"string","example":"ADJ-0001","description":"Sequential per organization."},"status":{"enum":["DRAFT","SUBMITTED","POSTED","REJECTED","CANCELLED"],"type":"string"},"reason":{"enum":["DAMAGED","SCRAPPED","FOUND"],"type":"string"},"direction":{"enum":["IN","OUT"],"type":"string","description":"Fixed by the reason."},"explanation":{"type":"string"},"reference":{"type":"string","nullable":true},"createdByMembershipId":{"type":"string","format":"uuid"},"createdByName":{"type":"string","nullable":true},"submittedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"submittedByName":{"type":"string","nullable":true},"submittedAt":{"format":"date-time","type":"string","nullable":true},"approvedByMembershipId":{"type":"string","nullable":true,"format":"uuid","description":"Who approved — and so posted — it."},"approvedByName":{"type":"string","nullable":true},"approvedAt":{"format":"date-time","type":"string","nullable":true},"rejectedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"rejectedByName":{"type":"string","nullable":true},"rejectedAt":{"format":"date-time","type":"string","nullable":true},"rejectionReason":{"type":"string","nullable":true},"cancelledByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"cancelledByName":{"type":"string","nullable":true},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"lineCount":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","storeId","storeCode","storeName","storeProjectId","inventoryAdjustmentNumber","status","reason","direction","explanation","reference","createdByMembershipId","createdByName","submittedByMembershipId","submittedByName","submittedAt","approvedByMembershipId","approvedByName","approvedAt","rejectedByMembershipId","rejectedByName","rejectedAt","rejectionReason","cancelledByMembershipId","cancelledByName","cancelledAt","cancellationReason","lineCount","createdAt","updatedAt"]},"UpdateInventoryAdjustmentDto":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"reason":{"enum":["DAMAGED","SCRAPPED","FOUND"],"type":"string"},"explanation":{"type":"string","maxLength":1000},"reference":{"type":"string","maxLength":100}}},"InventoryAdjustmentDecisionReasonDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000,"example":"Photograph the damage first"}},"required":["reason"]},"InventoryAdjustmentLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"inventoryAdjustmentId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"storeLocationId":{"type":"string","nullable":true,"format":"uuid"},"storeLocationCode":{"type":"string","nullable":true},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string","nullable":true},"stockItemName":{"type":"string","nullable":true},"baseUnit":{"type":"string","nullable":true},"quantity":{"type":"string","example":"2.0000","description":"Positive."},"signedQuantity":{"type":"string","example":"-2.0000","description":"The quantity with the reason’s sign — what posting writes to the ledger."},"notes":{"type":"string","nullable":true},"sortOrder":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","inventoryAdjustmentId","storeId","storeLocationId","storeLocationCode","stockItemId","stockItemCode","stockItemName","baseUnit","quantity","signedQuantity","notes","sortOrder","createdAt","updatedAt"]},"UpdateInventoryAdjustmentLineDto":{"type":"object","properties":{"quantity":{"type":"string","example":"3.0000"},"storeLocationId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":500},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}}},"CreateSalesOrderDto":{"type":"object","properties":{"clientId":{"type":"string","format":"uuid"},"stockItemId":{"type":"string","format":"uuid"},"storeId":{"type":"string","description":"A central store — never a project site.","format":"uuid"},"storeLocationId":{"type":"string","description":"The bin to sell from. Omit it and the store's unbinned stock is used, or —\nwhen all of it sits in bins — the one bin that can cover the quantity.","format":"uuid"},"quantity":{"type":"string","example":"20"},"unitPrice":{"type":"string","description":"Per base unit, excluding VAT.","example":"60000"},"paymentTerms":{"enum":["PREPAID","NET_7","NET_30"],"type":"string"},"handover":{"enum":["COLLECT","DELIVER"],"type":"string"},"chargeVat":{"type":"boolean","description":"VAT at 18%. Off for an exempt client.","example":true}},"required":["clientId","stockItemId","storeId","quantity","unitPrice","paymentTerms","handover","chargeVat"]},"SalesInvoiceSummaryDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"salesInvoiceNumber":{"type":"string","example":"SI-0001"},"issuedAt":{"format":"date-time","type":"string"},"dueDate":{"type":"string","example":"2026-11-13"}},"required":["id","salesInvoiceNumber","issuedAt","dueDate"]},"SalesOrderLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string"},"stockItemName":{"type":"string"},"storeId":{"type":"string","format":"uuid"},"storeCode":{"type":"string"},"storeName":{"type":"string"},"storeLocationId":{"type":"string","nullable":true,"format":"uuid"},"storeLocationCode":{"type":"string","nullable":true},"quantity":{"type":"string","example":"20.0000"},"unit":{"type":"string","example":"lengths"},"unitPrice":{"type":"string","example":"60000.00"},"unitCostAtSale":{"type":"string","example":"52000.0000"},"lineTotal":{"type":"string","example":"1200000.00"},"costOfGoods":{"type":"string","description":"quantity × unit cost at sale, 2dp.","example":"1040000.00"}},"required":["id","stockItemId","stockItemCode","stockItemName","storeId","storeCode","storeName","storeLocationId","storeLocationCode","quantity","unit","unitPrice","unitCostAtSale","lineTotal","costOfGoods"]},"SalesOrderDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"salesOrderNumber":{"type":"string","example":"SO-0001"},"status":{"enum":["PENDING_APPROVAL","RELEASED","REJECTED","CANCELLED"],"type":"string"},"clientId":{"type":"string","format":"uuid"},"clientName":{"type":"string"},"clientPhone":{"type":"string","nullable":true},"paymentTerms":{"enum":["PREPAID","NET_7","NET_30"],"type":"string"},"handover":{"enum":["COLLECT","DELIVER"],"type":"string"},"vatRate":{"type":"string","example":"0.1800"},"subtotal":{"type":"string","example":"1200000.00"},"vatAmount":{"type":"string","example":"216000.00"},"total":{"type":"string","example":"1416000.00"},"costOfGoods":{"type":"string","description":"Σ quantity × unit cost at sale — the inventory value that leaves.","example":"1040000.00"},"margin":{"type":"string","description":"subtotal − cost of goods. Negative below cost.","example":"160000.00"},"belowCost":{"type":"boolean","description":"A line is priced below its unit cost."},"overLimit":{"type":"boolean","description":"The total was over the organization’s sale approval limit."},"deliveryNoteNumber":{"type":"string","nullable":true,"example":"DN-0001"},"invoice":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/SalesInvoiceSummaryDto"}]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/SalesOrderLineDto"}},"createdByMembershipId":{"type":"string","format":"uuid"},"createdByName":{"type":"string","nullable":true},"approvedByName":{"type":"string","nullable":true},"approvedAt":{"format":"date-time","type":"string","nullable":true},"releasedByName":{"type":"string","nullable":true},"releasedAt":{"format":"date-time","type":"string","nullable":true},"rejectedByName":{"type":"string","nullable":true},"rejectedAt":{"format":"date-time","type":"string","nullable":true},"rejectionReason":{"type":"string","nullable":true},"cancelledByName":{"type":"string","nullable":true},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"cannotApproveReason":{"type":"string","nullable":true,"description":"Why the caller may not approve this order — they created it, lack\n`sales_order.approve`, or it is not awaiting approval — or null when they\nmay. The UI shows the reason rather than working it out."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","salesOrderNumber","status","clientId","clientName","clientPhone","paymentTerms","handover","vatRate","subtotal","vatAmount","total","costOfGoods","margin","belowCost","overLimit","deliveryNoteNumber","invoice","lines","createdByMembershipId","createdByName","approvedByName","approvedAt","releasedByName","releasedAt","rejectedByName","rejectedAt","rejectionReason","cancelledByName","cancelledAt","cancellationReason","cannotApproveReason","createdAt","updatedAt"]},"SalesOrderDecisionReasonDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000,"example":"Price agreed with the client is too low"}},"required":["reason"]},"ClientDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Kisakye Builders Ltd"},"phone":{"type":"string","nullable":true,"example":"+256706700953"},"email":{"type":"string","nullable":true},"tin":{"type":"string","nullable":true,"description":"Tax identification number."},"createdAt":{"format":"date-time","type":"string"}},"required":["id","name","phone","email","tin","createdAt"]},"CreateClientDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"example":"Kisakye Builders Ltd"},"phone":{"type":"string","maxLength":50,"example":"+256706700953"},"email":{"type":"string","maxLength":254,"format":"email"},"tin":{"type":"string","maxLength":50}},"required":["name"]},"SalesInvoiceDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"salesInvoiceNumber":{"type":"string","example":"SI-0001"},"status":{"enum":["UNPAID","OVERDUE","PAID"],"type":"string"},"issuedAt":{"format":"date-time","type":"string"},"issuedOn":{"type":"string","format":"date"},"dueDate":{"type":"string","format":"date"},"salesOrderId":{"type":"string","format":"uuid"},"salesOrderNumber":{"type":"string"},"deliveryNoteNumber":{"type":"string","nullable":true},"paymentTerms":{"enum":["PREPAID","NET_7","NET_30"],"type":"string"},"handover":{"enum":["COLLECT","DELIVER"],"type":"string"},"clientId":{"type":"string","format":"uuid"},"clientName":{"type":"string"},"clientPhone":{"type":"string","nullable":true},"clientEmail":{"type":"string","nullable":true},"clientTin":{"type":"string","nullable":true},"subtotal":{"type":"string"},"vatRate":{"type":"string"},"vatAmount":{"type":"string"},"total":{"type":"string"},"costOfGoods":{"type":"string","description":"Internal: what the goods cost."},"margin":{"type":"string","description":"Internal: subtotal − cost of goods."},"paidOn":{"type":"string","nullable":true,"format":"date"},"paidByName":{"type":"string","nullable":true},"paidRecordedAt":{"format":"date-time","type":"string","nullable":true}},"required":["id","salesInvoiceNumber","status","issuedAt","issuedOn","dueDate","salesOrderId","salesOrderNumber","deliveryNoteNumber","paymentTerms","handover","clientId","clientName","clientPhone","clientEmail","clientTin","subtotal","vatRate","vatAmount","total","costOfGoods","margin","paidOn","paidByName","paidRecordedAt"]},"SalesInvoiceCountsDto":{"type":"object","properties":{"all":{"type":"number"},"unpaid":{"type":"number"},"overdue":{"type":"number"},"paid":{"type":"number"}},"required":["all","unpaid","overdue","paid"]},"SalesInvoicePageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SalesInvoiceDto"}},"meta":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"},"hasNext":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasNext"]},"counts":{"description":"Per status, within the same search and date range — the chip counts.","allOf":[{"$ref":"#/components/schemas/SalesInvoiceCountsDto"}]}},"required":["items","meta","counts"]},"SalesInvoiceLineDto":{"type":"object","properties":{"stockItemCode":{"type":"string"},"stockItemName":{"type":"string"},"quantity":{"type":"string"},"unit":{"type":"string"},"unitPrice":{"type":"string"},"lineTotal":{"type":"string"},"storeName":{"type":"string"}},"required":["stockItemCode","stockItemName","quantity","unit","unitPrice","lineTotal","storeName"]},"SalesInvoiceEventDto":{"type":"object","properties":{"eventType":{"type":"string","enum":["MARKED_PAID","MARKED_UNPAID"]},"paidOn":{"type":"string","nullable":true,"format":"date"},"actorName":{"type":"string","nullable":true},"at":{"format":"date-time","type":"string"}},"required":["eventType","paidOn","actorName","at"]},"SalesInvoiceDetailDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"salesInvoiceNumber":{"type":"string","example":"SI-0001"},"status":{"enum":["UNPAID","OVERDUE","PAID"],"type":"string"},"issuedAt":{"format":"date-time","type":"string"},"issuedOn":{"type":"string","format":"date"},"dueDate":{"type":"string","format":"date"},"salesOrderId":{"type":"string","format":"uuid"},"salesOrderNumber":{"type":"string"},"deliveryNoteNumber":{"type":"string","nullable":true},"paymentTerms":{"enum":["PREPAID","NET_7","NET_30"],"type":"string"},"handover":{"enum":["COLLECT","DELIVER"],"type":"string"},"clientId":{"type":"string","format":"uuid"},"clientName":{"type":"string"},"clientPhone":{"type":"string","nullable":true},"clientEmail":{"type":"string","nullable":true},"clientTin":{"type":"string","nullable":true},"subtotal":{"type":"string"},"vatRate":{"type":"string"},"vatAmount":{"type":"string"},"total":{"type":"string"},"costOfGoods":{"type":"string","description":"Internal: what the goods cost."},"margin":{"type":"string","description":"Internal: subtotal − cost of goods."},"paidOn":{"type":"string","nullable":true,"format":"date"},"paidByName":{"type":"string","nullable":true},"paidRecordedAt":{"format":"date-time","type":"string","nullable":true},"lines":{"type":"array","items":{"$ref":"#/components/schemas/SalesInvoiceLineDto"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/SalesInvoiceEventDto"}}},"required":["id","salesInvoiceNumber","status","issuedAt","issuedOn","dueDate","salesOrderId","salesOrderNumber","deliveryNoteNumber","paymentTerms","handover","clientId","clientName","clientPhone","clientEmail","clientTin","subtotal","vatRate","vatAmount","total","costOfGoods","margin","paidOn","paidByName","paidRecordedAt","lines","events"]},"MarkSalesInvoicePaidDto":{"type":"object","properties":{"paidOn":{"type":"string","description":"The day the client paid; today when omitted. Never in the future.","format":"date"}}},"PaymentToMakePaymentDto":{"type":"object","properties":{"paymentId":{"type":"string","format":"uuid"},"batchId":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"200000.0000"},"paidOn":{"type":"string","format":"date"},"method":{"enum":["MOBILE_MONEY","BANK","CASH"],"type":"string"},"reference":{"type":"string","nullable":true},"note":{"type":"string","nullable":true},"paidByName":{"type":"string","nullable":true},"batchLineCount":{"type":"number","description":"Lines paid in the same batch, this one included."},"proofCount":{"type":"number","description":"Proof files attached to the batch."}},"required":["paymentId","batchId","amount","paidOn","method","batchLineCount","proofCount"]},"PaymentToMakeDto":{"type":"object","properties":{"requisitionLineId":{"type":"string","format":"uuid"},"requisitionId":{"type":"string","format":"uuid"},"requisitionNumber":{"type":"string","example":"REQ-0042"},"projectId":{"type":"string","format":"uuid"},"projectName":{"type":"string"},"projectCode":{"type":"string"},"requisitionTypeId":{"type":"string","format":"uuid"},"requisitionTypeName":{"type":"string","example":"Fuel"},"description":{"type":"string"},"payeeName":{"type":"string","nullable":true},"payeeAccount":{"type":"string","nullable":true},"payeeMethod":{"nullable":true,"enum":["MOBILE_MONEY","BANK","CASH"],"type":"string"},"currency":{"type":"string","nullable":true,"example":"UGX"},"approvedAmount":{"type":"string","example":"200000.0000","description":"The approved amount: the line’s estimated amount."},"approvedAt":{"format":"date-time","type":"string","nullable":true},"status":{"enum":["TO_PAY","PAID"],"type":"string"},"actualAlreadyRecorded":{"type":"string","nullable":true,"description":"An actual amount recorded by hand (Record actual) before this line was paid here. Kept as it is — shown so Finance does not pay the same cost twice."},"payment":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PaymentToMakePaymentDto"}]}},"required":["requisitionLineId","requisitionId","requisitionNumber","projectId","projectName","projectCode","requisitionTypeId","requisitionTypeName","description","approvedAmount","status"]},"FacetCountDto":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"count":{"type":"number"}},"required":["value","label","count"]},"PaymentsToMakeFacetsDto":{"type":"object","properties":{"status":{"type":"array","items":{"$ref":"#/components/schemas/FacetCountDto"}},"project":{"type":"array","items":{"$ref":"#/components/schemas/FacetCountDto"}},"type":{"type":"array","items":{"$ref":"#/components/schemas/FacetCountDto"}},"toPayTotals":{"description":"Approved amount of the lines still to pay, by currency.","type":"array","items":{"type":"string"}}},"required":["status","project","type","toPayTotals"]},"PaymentsToMakePageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PaymentToMakeDto"}},"meta":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"},"hasNext":{"type":"boolean"}},"required":["page","limit","total","totalPages","hasNext"]},"facets":{"description":"Counts for the filter chips. Each facet counts the matches under every OTHER filter, so a chip says how many rows choosing it would show.","allOf":[{"$ref":"#/components/schemas/PaymentsToMakeFacetsDto"}]}},"required":["items","meta","facets"]},"RecordedPaymentDto":{"type":"object","properties":{"batchId":{"type":"string","format":"uuid"},"paymentIds":{"type":"array","items":{"type":"string"}},"actualsSet":{"type":"number","description":"Lines whose actual amount this payment set."},"actualsKept":{"type":"number","description":"Lines that already had an actual recorded by hand; kept, not overwritten."}},"required":["batchId","paymentIds","actualsSet","actualsKept"]},"VoidRequisitionPaymentDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000}},"required":["reason"]},"RouteSwitchLineDto":{"type":"object","properties":{"requisitionLineId":{"type":"string","format":"uuid"},"requisitionId":{"type":"string","format":"uuid"},"requisitionNumber":{"type":"string","example":"REQ-0042"},"projectCode":{"type":"string"},"description":{"type":"string"},"reason":{"type":"string","nullable":true,"description":"Kept lines only: what procurement has already started — an RFQ, a quotation or a draft purchase order."}},"required":["requisitionLineId","requisitionId","requisitionNumber","projectCode","description"]},"RouteSwitchTypeDto":{"type":"object","properties":{"mappedName":{"type":"string","description":"The name in the agreed mapping."},"route":{"type":"string","enum":["STOCK","PURCHASE","PAY"]},"requisitionTypeId":{"type":"string","format":"uuid","nullable":true},"currentName":{"type":"string","nullable":true,"description":"The type’s name as it is now."},"currentRoute":{"type":"string","enum":["STOCK","PURCHASE","PAY"],"nullable":true},"renameTo":{"type":"string","nullable":true,"description":"The tidied name it will be renamed to, when different."},"linesMovingToPay":{"type":"number","description":"Approved stock lines with no procurement started that move to Payments to make (route PAY)."},"linesMovingToPurchase":{"type":"number","description":"Approved stock lines with no procurement started that move to Purchase, not stocked (route PURCHASE)."},"linesKeptProcurementStarted":{"type":"number","description":"Approved lines kept as stock because procurement has started on them: an RFQ, a quotation or a draft purchase order."},"linesWithPurchaseOrder":{"type":"number","description":"Approved lines on an issued or closed purchase order. Untouched; they finish on their current path."},"movingLines":{"type":"array","items":{"$ref":"#/components/schemas/RouteSwitchLineDto"}},"keptLines":{"type":"array","items":{"$ref":"#/components/schemas/RouteSwitchLineDto"}},"willCreate":{"type":"boolean","description":"Whether the switch-over creates this type."}},"required":["mappedName","route","linesMovingToPay","linesMovingToPurchase","linesKeptProcurementStarted","linesWithPurchaseOrder","movingLines","keptLines","willCreate"]},"RouteSwitchPreviewDto":{"type":"object","properties":{"types":{"type":"array","items":{"$ref":"#/components/schemas/RouteSwitchTypeDto"}},"groups":{"type":"object","description":"\"Moving to Payments to make\", \"Moving to Purchase, not stocked\" and \"Kept as stock (procurement started)\"."},"unmatchedNames":{"description":"Mapped names no type in this organization matches (ignoring case and extra spaces). Nothing happens for them.","type":"array","items":{"type":"string"}},"unmappedTypes":{"description":"Types in this organization the mapping does not mention. They keep their route.","type":"array","items":{"type":"string"}},"totals":{"type":"object"}},"required":["types","groups","unmatchedNames","unmappedTypes","totals"]},"RouteSwitchResultDto":{"type":"object","properties":{"types":{"type":"array","items":{"$ref":"#/components/schemas/RouteSwitchTypeDto"}},"groups":{"type":"object","description":"\"Moving to Payments to make\", \"Moving to Purchase, not stocked\" and \"Kept as stock (procurement started)\"."},"unmatchedNames":{"description":"Mapped names no type in this organization matches (ignoring case and extra spaces). Nothing happens for them.","type":"array","items":{"type":"string"}},"unmappedTypes":{"description":"Types in this organization the mapping does not mention. They keep their route.","type":"array","items":{"type":"string"}},"totals":{"type":"object"},"switchBatchId":{"type":"string","format":"uuid","description":"Pass to `POST /admin/requisition-routes/revert/{switchBatchId}` to undo it."}},"required":["types","groups","unmatchedNames","unmappedTypes","totals","switchBatchId"]},"RouteSwitchRevertDto":{"type":"object","properties":{"typesRestored":{"type":"number"},"linesRestored":{"type":"number"},"linesSkipped":{"description":"Lines left where the switch-over put them: a PAY line Finance has paid, or a PURCHASE line the requester has confirmed.","type":"array","items":{"type":"string"}}},"required":["typesRestored","linesRestored","linesSkipped"]},"ConfirmReceivedDto":{"type":"object","properties":{}},"CreateStockCountDto":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"countDate":{"type":"string","format":"date","example":"2026-10-24","description":"The day the stock is physically counted. Today, in the organization’s timezone, when omitted; never a future date."},"isBlind":{"type":"boolean","default":true,"description":"Blind: counters never see system quantities or variances, and reviewers give the variance reasons. Visible: counters see both and give the reasons themselves."},"description":{"type":"string","maxLength":500,"example":"Quarterly count, bays A–C"},"notes":{"type":"string","maxLength":2000},"scope":{"enum":["ALL_ITEMS","HELD_ONLY","CATEGORIES","MANUAL"],"type":"string","default":"MANUAL","description":"What to count. ALL_ITEMS: every active material in the catalogue — items with no stock here start at 0. HELD_ONLY: positions holding stock here now. CATEGORIES: every active material in `categoryIds`, subcategories included. MANUAL: no lines; add them one by one."},"categoryIds":{"uniqueItems":true,"maxItems":200,"description":"CATEGORIES only: at least one category or subcategory.","type":"array","items":{"type":"string","format":"uuid"}},"start":{"type":"boolean","default":false,"description":"Start counting at once, in the same transaction: needs `stock_count.update` as well, refuses an empty count, and snapshots every line."}},"required":["storeId"]},"StockCountVarianceSummaryDto":{"type":"object","properties":{"varianceLineCount":{"type":"number","description":"Counted lines whose variance is not zero."},"reasonMissingCount":{"type":"number","description":"Of those, how many have no reason yet."},"netVarianceValue":{"type":"string","example":"-1200000.0000","description":"Σ variance × unit cost. Negative is a shortage."},"grossVarianceValue":{"type":"string","example":"1450000.0000","description":"Σ |variance × unit cost| — what the finance limit is tested against."},"uncostedVarianceCount":{"type":"number","description":"Variances on items with no cost yet. Any at all requires the finance approval."},"postedValue":{"type":"string","nullable":true,"description":"Once posted: Σ quantity × unit cost of the adjustments it wrote."}},"required":["varianceLineCount","reasonMissingCount","netVarianceValue","grossVarianceValue","uncostedVarianceCount","postedValue"]},"StockCountApprovalDto":{"type":"object","properties":{"financeApprovalLimit":{"type":"string","description":"The organization’s finance limit, as it stands now."},"financeApprovalRequired":{"type":"boolean","nullable":true,"description":"Whether level 2 is needed, judged on the counts entered so far. Null while the count is blind to you."},"pendingLevel":{"nullable":true,"enum":[1,2],"type":"number","description":"The level the count waits on, if any."},"canApprove":{"type":"boolean","description":"You may act on the pending level now: approve, send back for recount and (level 1) give reasons."},"cannotApproveReason":{"type":"string","nullable":true,"description":"Why not, in words to show as they are."}},"required":["financeApprovalLimit","financeApprovalRequired","pendingLevel","canApprove","cannotApproveReason"]},"StockCountDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"storeCode":{"type":"string","nullable":true},"storeName":{"type":"string","nullable":true},"storeProjectId":{"type":"string","nullable":true,"format":"uuid"},"stockCountNumber":{"type":"string","example":"CNT-0001"},"status":{"enum":["DRAFT","COUNTING","SUBMITTED","AWAITING_FINANCE","POSTED","CANCELLED"],"type":"string"},"isReturned":{"type":"boolean","description":"Counting again after a reviewer sent positions back — `returnComment` says why."},"countDate":{"type":"string","format":"date","example":"2026-10-24"},"isBlind":{"type":"boolean"},"scope":{"enum":["ALL_ITEMS","HELD_ONLY","CATEGORIES","MANUAL"],"type":"string"},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdByMembershipId":{"type":"string","format":"uuid"},"createdByName":{"type":"string","nullable":true},"startedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"startedByName":{"type":"string","nullable":true},"startedAt":{"format":"date-time","type":"string","nullable":true},"submittedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"submittedByName":{"type":"string","nullable":true},"submittedAt":{"format":"date-time","type":"string","nullable":true},"approvedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"approvedByName":{"type":"string","nullable":true},"approvedAt":{"format":"date-time","type":"string","nullable":true},"level1ApprovedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"level1ApprovedByName":{"type":"string","nullable":true},"level1ApprovedAt":{"format":"date-time","type":"string","nullable":true},"returnedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"returnedByName":{"type":"string","nullable":true},"returnedAt":{"format":"date-time","type":"string","nullable":true},"returnComment":{"type":"string","nullable":true},"cancelledByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"cancelledByName":{"type":"string","nullable":true},"cancelledAt":{"format":"date-time","type":"string","nullable":true},"cancellationReason":{"type":"string","nullable":true},"lineCount":{"type":"number"},"countedLineCount":{"type":"number","description":"Lines with a count for their current round."},"linesWithPhotos":{"type":"number","description":"Lines carrying at least one evidence photo, so approvers know evidence exists."},"varianceSummary":{"nullable":true,"description":"Null while the count is blind to you: a counter of a blind count never sees variances, even summed. Reviewers, visible counts and posted counts carry it.","type":"object","allOf":[{"$ref":"#/components/schemas/StockCountVarianceSummaryDto"}]},"approval":{"description":"Where the approval chain stands, and what you can do in it.","allOf":[{"$ref":"#/components/schemas/StockCountApprovalDto"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","storeId","storeCode","storeName","storeProjectId","stockCountNumber","status","isReturned","countDate","isBlind","scope","description","notes","createdByMembershipId","createdByName","startedByMembershipId","startedByName","startedAt","submittedByMembershipId","submittedByName","submittedAt","approvedByMembershipId","approvedByName","approvedAt","level1ApprovedByMembershipId","level1ApprovedByName","level1ApprovedAt","returnedByMembershipId","returnedByName","returnedAt","returnComment","cancelledByMembershipId","cancelledByName","cancelledAt","cancellationReason","lineCount","countedLineCount","linesWithPhotos","varianceSummary","approval","createdAt","updatedAt"]},"StockCountStatusCountsDto":{"type":"object","properties":{"all":{"type":"number"},"open":{"type":"number","description":"Neither posted nor cancelled."},"counting":{"type":"number"},"awaiting":{"type":"number"},"approved":{"type":"number"},"closed":{"type":"number"},"waitingOnYou":{"type":"number","description":"Awaiting an approval you may give now."}},"required":["all","open","counting","awaiting","approved","closed","waitingOnYou"]},"StockCountScopeCategoryDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"itemCount":{"type":"number","description":"Positions choosing this category would count."}},"required":["id","name","itemCount"]},"StockCountScopePreviewDto":{"type":"object","properties":{"allItems":{"type":"number","description":"Positions \"every item in the catalogue\" counts: held positions plus one for each item the store has never held."},"heldOnly":{"type":"number","description":"Positions holding stock here now."},"categories":{"description":"Top-level categories, in the stores team’s order.","type":"array","items":{"$ref":"#/components/schemas/StockCountScopeCategoryDto"}}},"required":["allItems","heldOnly","categories"]},"StockCountEventDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventType":{"enum":["CREATED","LINES_ADDED","LINE_ADDED","STARTED","DATE_CHANGED","SUBMITTED","RETURNED","SENT_TO_FINANCE","POSTED","CANCELLED","REJECTED","PHOTO_ADDED","PHOTO_REMOVED"],"type":"string"},"summary":{"type":"string","example":"Count started"},"note":{"type":"string","nullable":true,"description":"A reason given with it."},"actorName":{"type":"string","nullable":true},"occurredAt":{"format":"date-time","type":"string"}},"required":["id","eventType","summary","note","actorName","occurredAt"]},"StockCountCandidateDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"baseUnit":{"type":"string"},"categoryPath":{"type":"string","example":"Waterproofing › Membranes"}},"required":["id","code","name","baseUnit","categoryPath"]},"UpdateStockCountDto":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"countDate":{"type":"string","format":"date","description":"Changeable until the count is submitted — a count keyed in from paper the next day was still taken the day before."},"isBlind":{"type":"boolean","description":"Draft counts only."},"description":{"type":"string","maxLength":500},"notes":{"type":"string","maxLength":2000}}},"StockCountRoundDto":{"type":"object","properties":{"round":{"type":"number"},"countedQuantity":{"type":"string","example":"98.0000"},"systemQuantity":{"type":"string","example":"100.0000"},"variance":{"type":"string","example":"-2.0000"},"countedByMembershipId":{"type":"string","format":"uuid"},"countedByName":{"type":"string","nullable":true},"countedAt":{"format":"date-time","type":"string"}},"required":["round","countedQuantity","systemQuantity","variance","countedByMembershipId","countedByName","countedAt"]},"StockCountVarianceDto":{"type":"object","properties":{"lineId":{"type":"string","format":"uuid"},"storeLocationId":{"type":"string","nullable":true,"format":"uuid"},"storeLocationCode":{"type":"string","nullable":true},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string"},"stockItemName":{"type":"string"},"baseUnit":{"type":"string"},"currentRound":{"type":"number"},"countedQuantity":{"type":"string","nullable":true,"description":"The effective count: the current round’s."},"systemQuantity":{"type":"string","nullable":true,"description":"The ledger balance snapshotted when that count was entered."},"variance":{"type":"string","nullable":true,"example":"-2.0000","description":"`countedQuantity − systemQuantity`, computed by PostgreSQL — exactly what posting writes."},"currentQuantity":{"type":"string","description":"The ledger balance now. Differs from `systemQuantity` when stock has moved since the count; the variance is still applied as a difference."},"stale":{"type":"boolean","description":"An adjustment has hit this position since it was counted; posting will refuse it until it is recounted."},"unitCost":{"type":"string","nullable":true,"description":"The item’s average cost when the count was entered."},"varianceValue":{"type":"string","nullable":true,"description":"variance × unitCost; null when either is unknown."},"varianceReason":{"nullable":true,"enum":["DAMAGED_WASTAGE","USED_NOT_RECORDED","DELIVERY_NOT_RECORDED","MEASUREMENT_UNIT_ERROR","THEFT_LOSS","OTHER"],"type":"string"},"varianceNote":{"type":"string","nullable":true},"evidenceNote":{"type":"string","nullable":true,"description":"The counter’s note on the evidence photos."},"photoCount":{"type":"number","description":"Evidence photos on this line, 0–6."},"firstPhotoThumbUrl":{"type":"string","nullable":true,"description":"The first evidence photo’s 160 px thumbnail. Not the item’s photo: see `stockItemPhotoThumbUrl`."},"rounds":{"type":"array","items":{"$ref":"#/components/schemas/StockCountRoundDto"}}},"required":["lineId","storeLocationId","storeLocationCode","stockItemId","stockItemCode","stockItemName","baseUnit","currentRound","countedQuantity","systemQuantity","variance","currentQuantity","stale","unitCost","varianceValue","varianceReason","varianceNote","evidenceNote","photoCount","firstPhotoThumbUrl","rounds"]},"RecountStockCountDto":{"type":"object","properties":{"lineIds":{"uniqueItems":true,"minItems":1,"description":"The lines to count again. Omit for every line whose count differs from the system — or every line, when none does.","type":"array","items":{"type":"string","format":"uuid"}},"reason":{"type":"string","maxLength":1000,"example":"Variance above tolerance"}},"required":["reason"]},"CancelStockCountDto":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000,"example":"Store closed for flooding"}},"required":["reason"]},"StockCountLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"stockCountId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"storeLocationId":{"type":"string","nullable":true,"format":"uuid"},"storeLocationCode":{"type":"string","nullable":true},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string","nullable":true},"stockItemName":{"type":"string","nullable":true},"baseUnit":{"type":"string","nullable":true},"stockItemCategoryPath":{"type":"string","nullable":true,"example":"Waterproofing › Membranes"},"stockItemPhotoThumbUrl":{"type":"string","nullable":true,"description":"The item’s 160 px photo thumbnail. Null when it has none."},"currentRound":{"type":"number","description":"1, or higher after a recount."},"countedQuantity":{"type":"string","nullable":true,"example":"98.0000","description":"What was counted in the current round, if anything yet."},"countedByMembershipId":{"type":"string","nullable":true,"format":"uuid"},"countedByName":{"type":"string","nullable":true},"countedAt":{"format":"date-time","type":"string","nullable":true},"recountReason":{"type":"string","nullable":true,"description":"Why this position is being recounted, if it is."},"sortOrder":{"type":"number"},"evidenceNote":{"type":"string","nullable":true,"description":"The counter’s note on the evidence photos."},"photoCount":{"type":"number","description":"Evidence photos on this line, 0–6."},"firstPhotoThumbUrl":{"type":"string","nullable":true,"description":"The first evidence photo’s 160 px thumbnail. Not the item’s photo: see `stockItemPhotoThumbUrl`."},"systemQuantity":{"type":"string","nullable":true,"description":"Visible counts only. The ledger balance: snapshotted when the position was counted, or — until then — when counting started."},"variance":{"type":"string","nullable":true,"description":"Visible counts only: counted − system."},"varianceReason":{"nullable":true,"enum":["DAMAGED_WASTAGE","USED_NOT_RECORDED","DELIVERY_NOT_RECORDED","MEASUREMENT_UNIT_ERROR","THEFT_LOSS","OTHER"],"type":"string","description":"Visible counts only."},"varianceNote":{"type":"string","nullable":true,"description":"Visible counts only."}},"required":["id","stockCountId","storeId","storeLocationId","storeLocationCode","stockItemId","stockItemCode","stockItemName","baseUnit","stockItemCategoryPath","stockItemPhotoThumbUrl","currentRound","countedQuantity","countedByMembershipId","countedByName","countedAt","recountReason","sortOrder","evidenceNote","photoCount","firstPhotoThumbUrl"]},"CreateStockCountLineDto":{"type":"object","properties":{"stockItemId":{"type":"string","format":"uuid"},"storeLocationId":{"type":"string","description":"A bin of the count's store; omit for unbinned stock. Never transit.","format":"uuid"},"sortOrder":{"type":"number","minimum":0,"maximum":1000000}},"required":["stockItemId"]},"PopulateStockCountDto":{"type":"object","properties":{"scope":{"type":"string","enum":["HELD_ONLY","ALL_ITEMS","CATEGORIES"],"default":"HELD_ONLY"},"categoryIds":{"uniqueItems":true,"maxItems":200,"type":"array","items":{"type":"string","format":"uuid"}},"storeLocationId":{"type":"string","format":"uuid","description":"Only positions in this bin (a cycle count of one bin)."}}},"PopulatedStockCountDto":{"type":"object","properties":{"added":{"type":"number","description":"How many positions were added.","example":12}},"required":["added"]},"RecordStockCountDto":{"type":"object","properties":{"countedQuantity":{"type":"string","example":"98.0000","description":"A non-negative decimal string: zero is a real count of an empty position."},"varianceReason":{"enum":["DAMAGED_WASTAGE","USED_NOT_RECORDED","DELIVERY_NOT_RECORDED","MEASUREMENT_UNIT_ERROR","THEFT_LOSS","OTHER"],"type":"string","description":"Visible counts only: why the count differs from the system quantity. Ignored when the count matches. On a blind count the reviewer gives it."},"varianceNote":{"type":"string","maxLength":500}},"required":["countedQuantity"]},"SetStockCountVarianceReasonDto":{"type":"object","properties":{"varianceReason":{"enum":["DAMAGED_WASTAGE","USED_NOT_RECORDED","DELIVERY_NOT_RECORDED","MEASUREMENT_UNIT_ERROR","THEFT_LOSS","OTHER"],"type":"string"},"varianceNote":{"type":"string","maxLength":500}},"required":["varianceReason"]},"StockCountLinePhotoDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"stockCountLineId":{"type":"string","format":"uuid"},"url":{"type":"string","description":"Main image, WebP, longest side ≤ 1600 px."},"thumbUrl":{"type":"string","description":"160 px square WebP thumbnail."},"originalName":{"type":"string","nullable":true},"width":{"type":"number"},"height":{"type":"number"},"sizeBytes":{"type":"number"},"uploadedByMembershipId":{"type":"string","format":"uuid"},"uploadedByName":{"type":"string","nullable":true},"uploadedAt":{"format":"date-time","type":"string"},"sortOrder":{"type":"number"}},"required":["id","stockCountLineId","url","thumbUrl","originalName","width","height","sizeBytes","uploadedByMembershipId","uploadedByName","uploadedAt","sortOrder"]},"UpdateStockCountLineDto":{"type":"object","properties":{"evidenceNote":{"type":"string","nullable":true,"maxLength":500,"description":"Blank or null clears it. Editable only while counting."}},"required":["evidenceNote"]},"DashboardKpiDto":{"type":"object","properties":{"kind":{"enum":["money","count","percent"],"type":"string"},"value":{"type":"string","nullable":true,"description":"`null` when it cannot be computed; `unavailableReason` says why."},"previous":{"type":"string","nullable":true,"description":"The same figure as at `scope.comparisonDate`, when it can be known."},"addedSinceComparison":{"type":"string","nullable":true,"description":"For flows, the amount added since the comparison date (month to date for\nall time) rather than a before/after pair."},"series":{"nullable":true,"description":"Six points, oldest first, the last one today.","type":"array","items":{"type":"string"}},"unavailableReason":{"type":"string","nullable":true},"historyNote":{"type":"string","nullable":true,"description":"Why `series`/`previous` are missing, or what they approximate."}},"required":["kind"]},"DashboardKpisDto":{"type":"object","properties":{"overdueApprovalsAmount":{"type":"string","description":"Their estimated total, a decimal string."},"contractBook":{"description":"Signed contract value of every project not cancelled.","allOf":[{"$ref":"#/components/schemas/DashboardKpiDto"}]},"activeProjects":{"description":"Projects in ACTIVE status.","allOf":[{"$ref":"#/components/schemas/DashboardKpiDto"}]},"activePastPlannedCompletion":{"type":"number","description":"ACTIVE projects whose planned completion date has passed."},"approvedBudget":{"description":"Revised amount of every live project's ACTIVE budget.","allOf":[{"$ref":"#/components/schemas/DashboardKpiDto"}]},"actualExpenditure":{"description":"Posted cost: approved invoices, certified subcontract work, recorded actuals.","allOf":[{"$ref":"#/components/schemas/DashboardKpiDto"}]},"utilisation":{"description":"(Actual + open commitments) ÷ approved budget, budgeted projects only.","allOf":[{"$ref":"#/components/schemas/DashboardKpiDto"}]},"overdueApprovals":{"description":"Submitted requisitions waiting longer than the approval threshold.","allOf":[{"$ref":"#/components/schemas/DashboardKpiDto"}]}},"required":["overdueApprovalsAmount","contractBook","activeProjects","activePastPlannedCompletion","approvedBudget","actualExpenditure","utilisation","overdueApprovals"]},"DashboardStatusCountsDto":{"type":"object","properties":{"PLANNED":{"type":"number"},"ACTIVE":{"type":"number"},"ON_HOLD":{"type":"number"},"COMPLETED":{"type":"number"},"CANCELLED":{"type":"number"}},"required":["PLANNED","ACTIVE","ON_HOLD","COMPLETED","CANCELLED"]},"DashboardBranchRowDto":{"type":"object","properties":{"branchId":{"type":"string","nullable":true,"description":"`null` for projects with no branch.","format":"uuid"},"name":{"type":"string","nullable":true},"projectCount":{"type":"number","description":"Live (not cancelled) projects."},"contractValue":{"type":"string","description":"Their contract value in the overview currency."},"atRiskCount":{"type":"number","description":"Projects rated Over budget or High risk."},"unknownRiskCount":{"type":"number","description":"Projects whose risk could not be judged (no budget, or budget hidden)."}},"required":["projectCount","contractValue","atRiskCount","unknownRiskCount"]},"DashboardPortfolioDto":{"type":"object","properties":{"statusCounts":{"$ref":"#/components/schemas/DashboardStatusCountsDto"},"projectCount":{"type":"number","description":"Every status, cancelled included."},"branches":{"description":"Largest contract first; unassigned last.","type":"array","items":{"$ref":"#/components/schemas/DashboardBranchRowDto"}},"total":{"description":"Computed by the same grouping as the rows, so it reconciles with them.","allOf":[{"$ref":"#/components/schemas/DashboardBranchRowDto"}]}},"required":["statusCounts","projectCount","branches","total"]},"DashboardPipelineBucketDto":{"type":"object","properties":{"status":{"enum":["DRAFT","SUBMITTED","APPROVED","REJECTED"],"type":"string"},"count":{"type":"number"},"amount":{"type":"string"}},"required":["status","count","amount"]},"DashboardAgeingBucketDto":{"type":"object","properties":{"maxDays":{"type":"number","nullable":true,"description":"Inclusive upper bound, or `null` for the open-ended last bucket."},"minDays":{"type":"number","description":"Inclusive lower bound in days waiting."},"count":{"type":"number"},"amount":{"type":"string"},"pastThreshold":{"type":"boolean","description":"Every requisition in this bucket is past the approval threshold."}},"required":["minDays","count","amount","pastThreshold"]},"DashboardPipelineDto":{"type":"object","properties":{"totalCount":{"type":"number","description":"Non-cancelled requisitions raised in the period: the four buckets' sum."},"totalAmount":{"type":"string"},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/DashboardPipelineBucketDto"}},"ageing":{"description":"Submitted requisitions by days waiting since submission.","type":"array","items":{"$ref":"#/components/schemas/DashboardAgeingBucketDto"}},"pastThresholdCount":{"type":"number","description":"Submitted requisitions in the period waiting past the threshold."},"ownOnly":{"type":"boolean","description":"True when narrowed to the caller's own requisitions (`view_own`)."}},"required":["totalCount","totalAmount","buckets","ageing","pastThresholdCount","ownOnly"]},"DashboardAlertProjectDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"projectCode":{"type":"string"},"name":{"type":"string"}},"required":["id","projectCode","name"]},"DashboardAlertDto":{"type":"object","properties":{"severity":{"enum":["CRITICAL","WARNING","INFO"],"type":"string"},"category":{"enum":["BUDGET","SCHEDULE","APPROVALS","DATA"],"type":"string"},"kind":{"enum":["OVER_BUDGET","NEAR_BUDGET_LIMIT","PAST_PLANNED_COMPLETION","DUE_SOON","APPROVALS_OVERDUE","MISSING_DETAILS"],"type":"string"},"project":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/DashboardAlertProjectDto"}]},"currency":{"type":"string","nullable":true},"utilisationPercent":{"type":"number","nullable":true},"budgetAmount":{"type":"string","nullable":true},"usedAmount":{"type":"string","nullable":true},"remainingAmount":{"type":"string","nullable":true},"plannedCompletionDate":{"type":"string","nullable":true,"format":"date"},"daysOverdue":{"type":"number","nullable":true},"daysUntilDue":{"type":"number","nullable":true},"requisitionCount":{"type":"number","nullable":true},"requisitionAmount":{"type":"string","nullable":true},"missing":{"type":"array","items":{"type":"string","enum":["contractValue","budget","branch"]}},"id":{"type":"string"}},"required":["severity","category","kind","missing","id"]},"DashboardProjectDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clientName":{"type":"string","nullable":true},"branchId":{"type":"string","nullable":true,"format":"uuid"},"branchName":{"type":"string","nullable":true},"status":{"enum":["PLANNED","ACTIVE","ON_HOLD","COMPLETED","CANCELLED"],"type":"string"},"currency":{"type":"string","nullable":true},"startDate":{"type":"string","nullable":true,"format":"date"},"plannedCompletionDate":{"type":"string","nullable":true,"format":"date"},"actualCompletionDate":{"type":"string","nullable":true,"format":"date"},"createdAt":{"type":"string","format":"date-time"},"contractValue":{"type":"string","nullable":true},"budget":{"type":"string","nullable":true,"description":"ACTIVE budget's revised amount; `null` without one or without `budget.view`."},"actual":{"type":"string","nullable":true,"description":"Posted cost; `null` without `budget.view`."},"committed":{"type":"string","nullable":true,"description":"Open commitments — committing orders and live subcontracts, less what has\nalready been invoiced or certified against them, so nothing is in both\n`actual` and here. `null` without `purchase_order.view`."},"remaining":{"type":"string","nullable":true,"description":"Budget − actual − committed; negative when over."},"utilisationPercent":{"type":"string","nullable":true,"description":"(Actual + committed) ÷ budget × 100, two places."},"timeElapsedPercent":{"type":"string","nullable":true,"description":"Share of start → planned completion elapsed, two places; past 100 when late."},"daysToPlannedCompletion":{"type":"number","nullable":true},"coverImageUrl":{"type":"string","nullable":true,"description":"The newest image attached to the project."},"projectCode":{"type":"string"},"name":{"type":"string"},"schedule":{"type":"string","enum":["COMPLETED","OVERDUE","DUE_SOON","ON_TRACK","NO_DATE"]},"risk":{"type":"string","enum":["OVER_BUDGET","HIGH","MEDIUM","LOW","UNKNOWN"]}},"required":["id","status","createdAt","projectCode","name","schedule","risk"]},"DashboardProjectTotalsDto":{"type":"object","properties":{"budget":{"type":"string","nullable":true},"actual":{"type":"string","nullable":true},"committed":{"type":"string","nullable":true},"remaining":{"type":"string","nullable":true,"description":"Σ (budget − actual − committed) over budgeted projects."},"utilisationPercent":{"type":"string","nullable":true,"description":"The utilisation KPI's ratio."},"projectCount":{"type":"number","description":"Live projects in the overview currency."}},"required":["projectCount"]},"DashboardExpenditureMonthDto":{"type":"object","properties":{"planned":{"type":"string","nullable":true,"description":"Always `null` today: no budget records a phased plan."},"month":{"type":"string","description":"`YYYY-MM`."},"toDate":{"type":"boolean","description":"The current month, counted to today."},"actual":{"type":"string"}},"required":["month","toDate","actual"]},"DashboardExpenditureDto":{"type":"object","properties":{"plannedUnavailableReason":{"type":"string","nullable":true},"months":{"type":"array","items":{"$ref":"#/components/schemas/DashboardExpenditureMonthDto"}},"totalActual":{"type":"string","description":"Sum of the six months."},"undatedActual":{"type":"string","description":"Manually entered actuals carry no date and appear in no month. Their\ntotal, so the gap is visible rather than silent."}},"required":["months","totalActual","undatedActual"]},"DashboardRequisitionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"requesterName":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"submittedAt":{"type":"string","nullable":true,"format":"date-time"},"requisitionNumber":{"type":"string"},"purpose":{"type":"string"},"projectCode":{"type":"string"},"projectName":{"type":"string"},"amount":{"type":"string"},"status":{"type":"string"}},"required":["id","projectId","createdAt","requisitionNumber","purpose","projectCode","projectName","amount","status"]},"DashboardScopeDto":{"type":"object","properties":{"branchId":{"type":"string","nullable":true,"format":"uuid"},"period":{"enum":["all_time","last_30_days","this_quarter","year_to_date"],"type":"string"},"periodStart":{"type":"string","nullable":true,"description":"First day inside the period, or `null` for all time.","format":"date"},"today":{"type":"string","description":"Today, in the organization's timezone.","format":"date"},"comparisonDate":{"type":"string","description":"The day changes are compared with, as at its close.","format":"date"},"unassigned":{"type":"boolean","description":"True when narrowed to projects with no branch."},"timezone":{"type":"string","description":"IANA timezone dates are bucketed and shown in."},"comparisonLabel":{"type":"string","description":"How the comparison reads after \"vs\": `Sep`, `21 Sep`, `Q3`, `2025`."}},"required":["period","today","comparisonDate","unassigned","timezone","comparisonLabel"]},"DashboardAccessDto":{"type":"object","properties":{"projects":{"type":"boolean","description":"`project.view`."},"budgets":{"type":"boolean","description":"`budget.view`: budgets, actuals and utilisation."},"commitments":{"type":"boolean","description":"`purchase_order.view`: commitments."},"requisitions":{"type":"boolean","description":"`requisition.view` or `requisition.view_own` (then only their own)."},"approvals":{"type":"boolean","description":"`approval.view`."}},"required":["projects","budgets","commitments","requisitions","approvals"]},"DashboardThresholdsDto":{"type":"object","properties":{"approvalOverdueDays":{"type":"number"},"budgetWarningPercent":{"type":"number"},"dueSoonDays":{"type":"number"},"overdueCriticalDays":{"type":"number"},"dueInfoDays":{"type":"number"},"spendAheadPoints":{"type":"number"}},"required":["approvalOverdueDays","budgetWarningPercent","dueSoonDays","overdueCriticalDays","dueInfoDays","spendAheadPoints"]},"CurrencyProjectCountDto":{"type":"object","properties":{"currency":{"type":"string","nullable":true},"projectCount":{"type":"number"}},"required":["projectCount"]},"DashboardOverviewDto":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time"},"currency":{"type":"string","nullable":true,"description":"The currency money figures are reported in: the one most live projects\nuse. Projects in any other currency are left out of money totals and\ncounted in `otherCurrencies`; amounts are never converted."},"kpis":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/DashboardKpisDto"}]},"portfolio":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/DashboardPortfolioDto"}]},"pipeline":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/DashboardPipelineDto"}]},"myPendingApprovalCount":{"type":"number","nullable":true,"description":"Approvals routed to the caller now; `null` without `approval.view`."},"alerts":{"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/DashboardAlertDto"}},"projects":{"nullable":true,"description":"Every live project in scope, riskiest first.","type":"array","items":{"$ref":"#/components/schemas/DashboardProjectDto"}},"projectTotals":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/DashboardProjectTotalsDto"}]},"expenditure":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/DashboardExpenditureDto"}]},"latestRequisitions":{"nullable":true,"description":"The six newest non-draft requisitions raised in the period.","type":"array","items":{"$ref":"#/components/schemas/DashboardRequisitionDto"}},"scope":{"$ref":"#/components/schemas/DashboardScopeDto"},"access":{"$ref":"#/components/schemas/DashboardAccessDto"},"thresholds":{"$ref":"#/components/schemas/DashboardThresholdsDto"},"otherCurrencies":{"type":"array","items":{"$ref":"#/components/schemas/CurrencyProjectCountDto"}}},"required":["generatedAt","scope","access","thresholds","otherCurrencies"]},"DashboardSettingsDto":{"type":"object","properties":{"approvalOverdueDays":{"type":"number","example":5,"description":"A submitted requisition waiting longer than this is overdue."},"budgetWarningPercent":{"type":"number","example":85,"description":"Budget use — (actual + committed) ÷ approved budget — at or above this percentage warns."},"dueSoonDays":{"type":"number","example":14,"description":"Planned completion within this many days is \"Due soon\"."},"overdueCriticalDays":{"type":"number","example":7,"description":"Past planned completion by at least this many days is critical; by fewer, a warning."},"dueInfoDays":{"type":"number","example":7,"description":"Planned completion within this many days raises an info alert."},"spendAheadPoints":{"type":"number","example":15,"description":"Budget use running ahead of time elapsed by more than this many points rates Medium risk and is labelled on the cost-vs-time chart."},"customized":{"type":"boolean","description":"False until the organization changes a threshold; the defaults apply."}},"required":["approvalOverdueDays","budgetWarningPercent","dueSoonDays","overdueCriticalDays","dueInfoDays","spendAheadPoints","customized"]},"UpdateDashboardSettingsDto":{"type":"object","properties":{"approvalOverdueDays":{"type":"number","minimum":1,"maximum":90},"budgetWarningPercent":{"type":"number","minimum":1,"maximum":100},"dueSoonDays":{"type":"number","minimum":1,"maximum":90},"overdueCriticalDays":{"type":"number","minimum":1,"maximum":90},"dueInfoDays":{"type":"number","minimum":0,"maximum":90},"spendAheadPoints":{"type":"number","minimum":1,"maximum":100}}},"InventoryAccessDto":{"type":"object","properties":{"purchaseOrders":{"type":"boolean","description":"`purchase_order.view`: open orders, suppliers and lead times are shown. Without it they are withheld and alerts that depend on them are not raised."},"requisitions":{"type":"boolean","description":"`requisition.view`: requisitions waiting for stock are counted and named."},"salesOrders":{"type":"boolean","description":"`sales_order.view`: sales are linked and their clients named. Without it a sale reads \"to Client\"."}},"required":["purchaseOrders","requisitions","salesOrders"]},"StockValueKpiDto":{"type":"object","properties":{"value":{"type":"string","example":"187500000.0000"},"itemCount":{"type":"number"},"locationCount":{"type":"number"},"uncostedItemCount":{"type":"number","description":"Items held with no cost yet (never received on a priced order). Their stock is in the counts but not in the value."}},"required":["value","itemCount","locationCount","uncostedItemCount"]},"RequisitionsWaitingKpiDto":{"type":"object","properties":{"count":{"type":"number"},"oldestWaitingDays":{"type":"number","nullable":true}},"required":["count","oldestWaitingDays"]},"ShortestCoverKpiDto":{"type":"object","properties":{"stockItemId":{"type":"string","format":"uuid"},"name":{"type":"string"},"coverDays":{"type":"number","example":3.6}},"required":["stockItemId","name","coverDays"]},"IssuedThisMonthKpiDto":{"type":"object","properties":{"value":{"type":"string","example":"125000000.0000"},"monthName":{"type":"string","example":"October"},"uncostedCount":{"type":"number","description":"Issues this month with no cost to value."}},"required":["value","monthName","uncostedCount"]},"InventoryOverviewKpisDto":{"type":"object","properties":{"stockValue":{"$ref":"#/components/schemas/StockValueKpiDto"},"belowReorderCount":{"type":"number","description":"Items whose warehouse stock is at or below their reorder level, out of stock included."},"outOfStockCount":{"type":"number"},"reservedShortCount":{"type":"number","description":"Of the low and out-of-stock items, how many have stock reserved for sales awaiting approval — the \"{n} reserved\" note on the shortage KPIs."},"requisitionsWaiting":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/RequisitionsWaitingKpiDto"}]},"shortestCover":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ShortestCoverKpiDto"}]},"issuedThisMonth":{"$ref":"#/components/schemas/IssuedThisMonthKpiDto"}},"required":["stockValue","belowReorderCount","outOfStockCount","reservedShortCount","requisitionsWaiting","shortestCover","issuedThisMonth"]},"OpenOrderDto":{"type":"object","properties":{"purchaseOrderId":{"type":"string","format":"uuid"},"purchaseOrderNumber":{"type":"string","example":"PO-0121"},"projectId":{"type":"string","format":"uuid"},"quantity":{"type":"string","example":"200.0000","description":"Still to arrive on this order, in the base unit."},"expectedDeliveryDate":{"type":"string","nullable":true,"format":"date"},"supplierName":{"type":"string","nullable":true}},"required":["purchaseOrderId","purchaseOrderNumber","projectId","quantity","expectedDeliveryDate","supplierName"]},"CoverItemDto":{"type":"object","properties":{"stockItemId":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"baseUnit":{"type":"string"},"categoryId":{"type":"string","format":"uuid","description":"Its top-level category."},"categoryName":{"type":"string"},"centralQuantity":{"type":"string","example":"240.0000"},"dailyUse":{"type":"string","example":"32.00","description":"Average daily issue from the warehouses, last 28 days."},"coverDays":{"type":"number","example":7.5},"leadTimeDays":{"type":"number","nullable":true,"example":7},"tone":{"enum":["SHORT","TIGHT","OK"],"type":"string"},"openOrder":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/OpenOrderDto"}]}},"required":["stockItemId","code","name","baseUnit","categoryId","categoryName","centralQuantity","dailyUse","coverDays","leadTimeDays","tone","openOrder"]},"DaysOfCoverDto":{"type":"object","properties":{"items":{"description":"Lowest cover first. Every item with usage, not just seven.","type":"array","items":{"$ref":"#/components/schemas/CoverItemDto"}},"excludedNoUsageCount":{"type":"number","description":"Items held in the warehouses but left out: no issues in the last 28 days, so no rate to divide by."}},"required":["items","excludedNoUsageCount"]},"CategoryGroupDto":{"type":"object","properties":{"id":{"type":"string","description":"A category id, or `OTHER`.","example":"OTHER"},"name":{"type":"string","example":"Steel"}},"required":["id","name"]},"GroupValueDto":{"type":"object","properties":{"group":{"type":"string","description":"A `CategoryGroupDto.id`."},"value":{"type":"string"}},"required":["group","value"]},"WeeklyIssuesDto":{"type":"object","properties":{"weekStart":{"type":"string","format":"date","description":"The Monday the week starts."},"total":{"type":"string"},"segments":{"type":"array","items":{"$ref":"#/components/schemas/GroupValueDto"}},"uncostedCount":{"type":"number","description":"Issues in the week with no cost to value."}},"required":["weekStart","total","segments","uncostedCount"]},"InventoryAlertDto":{"type":"object","properties":{"kind":{"enum":["OUT_OF_STOCK_ON_ORDER","OUT_OF_STOCK_NOT_ORDERED","LOW_COVER_NOT_ORDERED","UNUSUAL_USAGE","HELD_PAST_COMPLETION","DELIVERY_DUE","COUNT_OVERDUE"],"type":"string"},"severity":{"enum":["CRITICAL","WARNING","INFO"],"type":"string"},"title":{"type":"string"},"context":{"type":"string"},"action":{"enum":["TRACK_PO","RAISE_REQUISITION","SEE_MOVEMENTS","RETURN_TO_STORE","PREPARE_RECEIPT","OPEN_STOCK_COUNT"],"type":"string"},"stockItemId":{"type":"string","nullable":true,"format":"uuid"},"storeId":{"type":"string","nullable":true,"format":"uuid"},"projectId":{"type":"string","nullable":true,"format":"uuid"},"purchaseOrderId":{"type":"string","nullable":true,"format":"uuid"},"purchaseOrderNumber":{"type":"string","nullable":true},"requisitionId":{"type":"string","nullable":true,"format":"uuid"},"requisitionNumber":{"type":"string","nullable":true}},"required":["kind","severity","title","context","action","stockItemId","storeId","projectId","purchaseOrderId","purchaseOrderNumber","requisitionId","requisitionNumber"]},"SourceDocumentDto":{"type":"object","properties":{"kind":{"enum":["PURCHASE_ORDER","REQUISITION","STOCK_COUNT","SALES_ORDER"],"type":"string"},"id":{"type":"string","format":"uuid"},"number":{"type":"string","example":"PO-0114"}},"required":["kind","id","number"]},"InventoryActivityDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"movedAt":{"format":"date-time","type":"string"},"movementType":{"enum":["RECEIPT","ISSUE","TRANSFER","ADJUSTMENT","RETURN","SUPPLIER_RETURN","REVERSAL","SALE"],"type":"string"},"quantity":{"type":"string","example":"-120.0000","description":"Signed: positive into a store, negative out. A transfer is shown as the quantity moved, positive."},"value":{"type":"string","nullable":true,"description":"quantity × the unit cost it moved at."},"stockItemId":{"type":"string","format":"uuid"},"stockItemCode":{"type":"string"},"stockItemName":{"type":"string"},"baseUnit":{"type":"string"},"from":{"type":"string","example":"Kampala Main Store"},"to":{"type":"string","example":"Mulago UCI PET Project"},"storeId":{"type":"string","format":"uuid"},"projectId":{"type":"string","nullable":true,"format":"uuid"},"documentId":{"type":"string","nullable":true,"format":"uuid"},"documentNumber":{"type":"string","nullable":true,"example":"GRN-0142"},"deliveryNoteNumber":{"type":"string","nullable":true,"example":"DN-0001","description":"A sale’s delivery note."},"sourceDocument":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/SourceDocumentDto"}]},"stockCountLineId":{"type":"string","nullable":true,"format":"uuid","description":"The count line a stock count adjustment came from."},"stockCountLinePhotoCount":{"type":"number","description":"Evidence photos on that count line (0 when none, or not from a count). Linked, never copied: read them at `GET /stock-counts/{documentId}/lines/{stockCountLineId}/photos`."},"movedByName":{"type":"string","nullable":true}},"required":["id","movedAt","movementType","quantity","value","stockItemId","stockItemCode","stockItemName","baseUnit","from","to","storeId","projectId","documentId","documentNumber","deliveryNoteNumber","sourceDocument","stockCountLineId","stockCountLinePhotoCount","movedByName"]},"InventoryOverviewDto":{"type":"object","properties":{"generatedAt":{"format":"date-time","type":"string"},"currency":{"type":"string","example":"UGX","description":"The currency values are in: the one most of the organization’s orders use. Nothing converts."},"access":{"$ref":"#/components/schemas/InventoryAccessDto"},"thresholds":{"$ref":"#/components/schemas/InventorySettingsDto"},"kpis":{"$ref":"#/components/schemas/InventoryOverviewKpisDto"},"daysOfCover":{"$ref":"#/components/schemas/DaysOfCoverDto"},"categoryGroups":{"description":"The slices `valueByGroup` and `weeklyIssues` use, in order: the top-level categories holding the most value (then issued most), at most five, and `OTHER` for the rest when there is a rest.","type":"array","items":{"$ref":"#/components/schemas/CategoryGroupDto"}},"valueByGroup":{"type":"array","items":{"$ref":"#/components/schemas/GroupValueDto"}},"weeklyIssues":{"type":"array","items":{"$ref":"#/components/schemas/WeeklyIssuesDto"}},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/InventoryAlertDto"}},"latestActivity":{"type":"array","items":{"$ref":"#/components/schemas/InventoryActivityDto"}}},"required":["generatedAt","currency","access","thresholds","kpis","daysOfCover","categoryGroups","valueByGroup","weeklyIssues","alerts","latestActivity"]},"MaterialRowDto":{"type":"object","properties":{"stockItemId":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"baseUnit":{"type":"string"},"categoryId":{"type":"string","format":"uuid"},"categoryName":{"type":"string"},"subcategoryId":{"type":"string","nullable":true,"format":"uuid"},"subcategoryName":{"type":"string","nullable":true},"categoryPath":{"type":"string","example":"Waterproofing › Membranes"},"photoUrl":{"type":"string","nullable":true,"description":"The item photo, within 1600 px, WebP. Null when none."},"photoThumbUrl":{"type":"string","nullable":true,"description":"A 160 px square crop of the photo. Null when none."},"reorderLevel":{"type":"string","nullable":true,"description":"Null when none is set: then status rests on quantity alone."},"averageUnitCost":{"type":"string","nullable":true},"onHand":{"type":"string","description":"On hand in the stores in scope."},"value":{"type":"string","nullable":true,"description":"onHand × cost."},"centralQuantity":{"type":"string","description":"Across every warehouse, whatever the scope."},"reserved":{"type":"string","example":"90.0000","description":"Held in central stores for sales awaiting approval — part of `centralQuantity`, not available to issue, transfer or sell."},"centralAvailable":{"type":"string","example":"10.0000","description":"`centralQuantity` − `reserved`. Status, the reorder chips and the cover alerts are judged by this."},"siteQuantity":{"type":"string","description":"Across every site store."},"status":{"enum":["NOT_STOCKED","OUT_OF_STOCK","LOW_STOCK","IN_STOCK","SITE_ONLY"],"type":"string","description":"Judged on warehouse stock against the reorder level. NOT_STOCKED: never received anywhere — not in reorder alerts or the out-of-stock and below-reorder counts."},"centralStoreCount":{"type":"number","description":"Warehouses in scope holding it."},"siteStoreCount":{"type":"number","description":"Site stores in scope holding it."},"openOrder":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/OpenOrderDto"}]}},"required":["stockItemId","code","name","baseUnit","categoryId","categoryName","subcategoryId","subcategoryName","categoryPath","photoUrl","photoThumbUrl","reorderLevel","averageUnitCost","onHand","value","centralQuantity","reserved","centralAvailable","siteQuantity","status","centralStoreCount","siteStoreCount","openOrder"]},"CursorMetaDto":{"type":"object","properties":{"limit":{"type":"number"},"nextCursor":{"type":"string","nullable":true,"description":"Pass as `cursor` for the next page; null on the last."},"hasNext":{"type":"boolean"}},"required":["limit","nextCursor","hasNext"]},"InventoryMovementsPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryActivityDto"}},"meta":{"$ref":"#/components/schemas/CursorMetaDto"}},"required":["items","meta"]},"NextDeliveryDto":{"type":"object","properties":{"purchaseOrderId":{"type":"string","format":"uuid"},"purchaseOrderNumber":{"type":"string","example":"PO-0119"},"projectId":{"type":"string","format":"uuid"},"expectedDeliveryDate":{"type":"string","format":"date"},"supplierName":{"type":"string","nullable":true}},"required":["purchaseOrderId","purchaseOrderNumber","projectId","expectedDeliveryDate","supplierName"]},"DeliveriesExpectedDto":{"type":"object","properties":{"count":{"type":"number","description":"Open orders still bringing stock."},"next":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/NextDeliveryDto"}]}},"required":["count","next"]},"MaterialsKpisDto":{"type":"object","properties":{"stockValue":{"type":"string"},"itemCount":{"type":"number"},"centralValue":{"type":"string"},"siteValue":{"type":"string"},"belowReorderCount":{"type":"number"},"belowReorderOnOrderCount":{"type":"number","nullable":true,"description":"Of those, how many have an open order. Null without `purchase_order.view`."},"outOfStockCount":{"type":"number"},"reservedShortCount":{"type":"number","description":"Of the low and out-of-stock items, how many have stock reserved for sales awaiting approval — the \"{n} reserved\" note on the shortage KPIs."},"deliveriesExpected":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/DeliveriesExpectedDto"}]},"uncostedItemCount":{"type":"number"}},"required":["stockValue","itemCount","centralValue","siteValue","belowReorderCount","belowReorderOnOrderCount","outOfStockCount","reservedShortCount","deliveriesExpected","uncostedItemCount"]},"StoreValueDto":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"storeCode":{"type":"string"},"storeName":{"type":"string"},"kind":{"enum":["CENTRAL","SITE"],"type":"string"},"projectId":{"type":"string","nullable":true,"format":"uuid"},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"itemCount":{"type":"number"},"value":{"type":"string"},"uncostedItemCount":{"type":"number"}},"required":["storeId","storeCode","storeName","kind","projectId","projectCode","projectName","itemCount","value","uncostedItemCount"]},"StockStatusCountsDto":{"type":"object","properties":{"all":{"type":"number","description":"Every item in scope."},"belowReorder":{"type":"number"},"outOfStock":{"type":"number"},"notStocked":{"type":"number"}},"required":["all","belowReorder","outOfStock","notStocked"]},"InventoryMaterialsDto":{"type":"object","properties":{"generatedAt":{"format":"date-time","type":"string"},"currency":{"type":"string","example":"UGX"},"access":{"$ref":"#/components/schemas/InventoryAccessDto"},"kpis":{"$ref":"#/components/schemas/MaterialsKpisDto"},"reorderAlerts":{"description":"Below reorder level in the warehouses — out of stock first. The first twelve; `reorderAlertCount` is all of them.","type":"array","items":{"$ref":"#/components/schemas/MaterialRowDto"}},"reorderAlertCount":{"type":"number"},"valueByStore":{"type":"array","items":{"$ref":"#/components/schemas/StoreValueDto"}},"statusCounts":{"description":"How many rows the stock table holds for each chip, in the same scope. The rows themselves are `GET /inventory/stock`, a page at a time.","allOf":[{"$ref":"#/components/schemas/StockStatusCountsDto"}]},"recentMovements":{"type":"array","items":{"$ref":"#/components/schemas/InventoryActivityDto"}}},"required":["generatedAt","currency","access","kpis","reorderAlerts","reorderAlertCount","valueByStore","statusCounts","recentMovements"]},"ItemStoreDto":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"storeCode":{"type":"string"},"storeName":{"type":"string"},"kind":{"enum":["CENTRAL","SITE"],"type":"string"},"projectId":{"type":"string","nullable":true,"format":"uuid"},"projectCode":{"type":"string","nullable":true},"projectName":{"type":"string","nullable":true},"quantity":{"type":"string"},"value":{"type":"string","nullable":true},"openStockCountNumber":{"type":"string","nullable":true,"description":"A count holding this store: nothing can leave it."},"reserved":{"type":"string","example":"10.0000","description":"Held for sales awaiting approval: part of `quantity`, but not available to issue, transfer or sell."}},"required":["storeId","storeCode","storeName","kind","projectId","projectCode","projectName","quantity","value","openStockCountNumber","reserved"]},"PendingSaleDto":{"type":"object","properties":{"salesOrderId":{"type":"string","nullable":true,"format":"uuid","description":"Null without `sales_order.view`."},"salesOrderNumber":{"type":"string","nullable":true,"example":"SO-0002"},"clientName":{"type":"string","nullable":true},"storeId":{"type":"string","format":"uuid"},"storeName":{"type":"string"},"quantity":{"type":"string","example":"10.0000"},"createdAt":{"format":"date-time","type":"string"}},"required":["salesOrderId","salesOrderNumber","clientName","storeId","storeName","quantity","createdAt"]},"LinkedRequisitionDto":{"type":"object","properties":{"requisitionId":{"type":"string","format":"uuid"},"requisitionNumber":{"type":"string"},"projectId":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["requisitionId","requisitionNumber","projectId","status"]},"InventoryMaterialDetailDto":{"type":"object","properties":{"stockItemId":{"type":"string","format":"uuid"},"byStore":{"type":"array","items":{"$ref":"#/components/schemas/ItemStoreDto"}},"recentMovements":{"type":"array","items":{"$ref":"#/components/schemas/InventoryActivityDto"}},"pendingSales":{"description":"What the stores’ `reserved` quantities are held for.","type":"array","items":{"$ref":"#/components/schemas/PendingSaleDto"}},"lastSupplierName":{"type":"string","nullable":true},"openOrder":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/OpenOrderDto"}]},"lastRequisition":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/LinkedRequisitionDto"}]},"siteValue":{"type":"string","nullable":true,"description":"Held at project sites, already charged to their budgets."}},"required":["stockItemId","byStore","recentMovements","pendingSales","lastSupplierName","openOrder","lastRequisition","siteValue"]},"EquipmentLocationDto":{"type":"object","properties":{"kind":{"enum":["WAREHOUSE","SITE","VENDOR","NONE"],"type":"string"},"storeId":{"type":"string","nullable":true,"format":"uuid"},"projectId":{"type":"string","nullable":true,"format":"uuid"},"projectCode":{"type":"string","nullable":true,"example":"TB-2026-103"},"name":{"type":"string","example":"Mulago UCI PET Project"}},"required":["kind","storeId","projectId","projectCode","name"]},"EquipmentDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tag":{"type":"string","example":"EQ-0012"},"name":{"type":"string"},"categoryId":{"type":"string","format":"uuid"},"subcategoryId":{"type":"string","nullable":true,"format":"uuid"},"categoryPath":{"type":"string","example":"Concrete plant › Mixers"},"make":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNo":{"type":"string","nullable":true},"year":{"type":"number","nullable":true},"status":{"enum":["IN_STORE","ON_SITE","UNDER_REPAIR","OUT_OF_SERVICE","DISPOSED"],"type":"string"},"location":{"$ref":"#/components/schemas/EquipmentLocationDto"},"onSiteSince":{"type":"string","nullable":true,"format":"date"},"daysOnSite":{"type":"number","nullable":true,"description":"Days on its current site."},"purchaseValue":{"type":"string","nullable":true},"dayRate":{"type":"string","nullable":true},"serviceIntervalDays":{"type":"number","nullable":true},"nextServiceDate":{"type":"string","nullable":true,"format":"date"},"daysToService":{"type":"number","nullable":true,"description":"Days until the next service; negative when overdue."},"serviceVendorId":{"type":"string","nullable":true,"format":"uuid"},"serviceVendorName":{"type":"string","nullable":true},"chargedToDate":{"type":"string","description":"Day rate × days on site, every stay so far. Not posted to budgets."},"disposalReason":{"type":"string","nullable":true},"actions":{"type":"array","items":{"type":"string","enum":["ISSUE","TRANSFER","RETURN","SERVICE_OUT","SERVICE_IN","MARK_AVAILABLE","OUT_OF_SERVICE","DISPOSE"]},"description":"What can be done with it from where it stands."},"createdAt":{"format":"date-time","type":"string"}},"required":["id","tag","name","categoryId","subcategoryId","categoryPath","make","model","serialNo","year","status","location","onSiteSince","daysOnSite","purchaseValue","dayRate","serviceIntervalDays","nextServiceDate","daysToService","serviceVendorId","serviceVendorName","chargedToDate","disposalReason","actions","createdAt"]},"EquipmentAlertDto":{"type":"object","properties":{"kind":{"enum":["OUT_OF_SERVICE","UNDER_REPAIR","SERVICE_OVERDUE","SERVICE_DUE"],"type":"string"},"assetId":{"type":"string","format":"uuid"},"tag":{"type":"string"},"name":{"type":"string"},"location":{"type":"string"},"nextServiceDate":{"type":"string","nullable":true,"format":"date"},"vendorName":{"type":"string","nullable":true,"description":"Under repair: who has it."}},"required":["kind","assetId","tag","name","location","nextServiceDate","vendorName"]},"EquipmentValueByLocationDto":{"type":"object","properties":{"kind":{"enum":["WAREHOUSE","SITE","VENDOR"],"type":"string"},"storeId":{"type":"string","nullable":true,"format":"uuid"},"projectId":{"type":"string","nullable":true,"format":"uuid"},"projectCode":{"type":"string","nullable":true},"name":{"type":"string"},"itemCount":{"type":"number"},"value":{"type":"string"}},"required":["kind","storeId","projectId","projectCode","name","itemCount","value"]},"EquipmentSummaryDto":{"type":"object","properties":{"currency":{"type":"string","example":"UGX"},"total":{"type":"number"},"onSite":{"type":"number"},"onSiteProjects":{"type":"number","description":"Projects with equipment on site."},"inStore":{"type":"number"},"unavailable":{"type":"number","description":"Under repair or out of service."},"underRepair":{"type":"number"},"outOfService":{"type":"number"},"serviceDue":{"type":"number","description":"Service due within the threshold, or overdue."},"serviceDueDays":{"type":"number"},"nextServiceName":{"type":"string","nullable":true,"example":"Generator 20 kVA"},"chargedToProjects":{"type":"string","description":"Every stay so far, day rate × days. A report."},"assetValue":{"type":"string"},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/EquipmentAlertDto"}},"valueByLocation":{"type":"array","items":{"$ref":"#/components/schemas/EquipmentValueByLocationDto"}}},"required":["currency","total","onSite","onSiteProjects","inStore","unavailable","underRepair","outOfService","serviceDue","serviceDueDays","nextServiceName","chargedToProjects","assetValue","alerts","valueByLocation"]},"CreateEquipmentDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"example":"Concrete mixer 350 L (diesel)"},"tag":{"type":"string","description":"Omit for the next EQ-#### number.","maxLength":16,"example":"EQ-0012"},"categoryId":{"type":"string","format":"uuid"},"subcategoryId":{"type":"string","format":"uuid"},"make":{"type":"string","maxLength":100},"model":{"type":"string","maxLength":100},"serialNo":{"type":"string","maxLength":100},"year":{"type":"number","minimum":1950,"maximum":2100},"purchaseValue":{"type":"string","example":"18500000.0000"},"dayRate":{"type":"string","example":"120000.0000","description":"Charged per day on site."},"serviceIntervalDays":{"type":"number","minimum":1,"maximum":3650},"nextServiceDate":{"type":"string","format":"date"},"serviceVendorId":{"type":"string","format":"uuid","description":"The supplier that services it."},"storeId":{"type":"string","format":"uuid","description":"The warehouse it starts in."}},"required":["name","categoryId","storeId"]},"EquipmentChargeDto":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"projectName":{"type":"string"},"projectCode":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","nullable":true,"format":"date"},"days":{"type":"number"},"dayRate":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true}},"required":["projectId","projectName","projectCode","startDate","endDate","days","dayRate","amount"]},"EquipmentDetailDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tag":{"type":"string","example":"EQ-0012"},"name":{"type":"string"},"categoryId":{"type":"string","format":"uuid"},"subcategoryId":{"type":"string","nullable":true,"format":"uuid"},"categoryPath":{"type":"string","example":"Concrete plant › Mixers"},"make":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNo":{"type":"string","nullable":true},"year":{"type":"number","nullable":true},"status":{"enum":["IN_STORE","ON_SITE","UNDER_REPAIR","OUT_OF_SERVICE","DISPOSED"],"type":"string"},"location":{"$ref":"#/components/schemas/EquipmentLocationDto"},"onSiteSince":{"type":"string","nullable":true,"format":"date"},"daysOnSite":{"type":"number","nullable":true,"description":"Days on its current site."},"purchaseValue":{"type":"string","nullable":true},"dayRate":{"type":"string","nullable":true},"serviceIntervalDays":{"type":"number","nullable":true},"nextServiceDate":{"type":"string","nullable":true,"format":"date"},"daysToService":{"type":"number","nullable":true,"description":"Days until the next service; negative when overdue."},"serviceVendorId":{"type":"string","nullable":true,"format":"uuid"},"serviceVendorName":{"type":"string","nullable":true},"chargedToDate":{"type":"string","description":"Day rate × days on site, every stay so far. Not posted to budgets."},"disposalReason":{"type":"string","nullable":true},"actions":{"type":"array","items":{"type":"string","enum":["ISSUE","TRANSFER","RETURN","SERVICE_OUT","SERVICE_IN","MARK_AVAILABLE","OUT_OF_SERVICE","DISPOSE"]},"description":"What can be done with it from where it stands."},"createdAt":{"format":"date-time","type":"string"},"charges":{"description":"Every stay on site, newest first.","type":"array","items":{"$ref":"#/components/schemas/EquipmentChargeDto"}}},"required":["id","tag","name","categoryId","subcategoryId","categoryPath","make","model","serialNo","year","status","location","onSiteSince","daysOnSite","purchaseValue","dayRate","serviceIntervalDays","nextServiceDate","daysToService","serviceVendorId","serviceVendorName","chargedToDate","disposalReason","actions","createdAt","charges"]},"UpdateEquipmentDto":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"categoryId":{"type":"string","format":"uuid"},"subcategoryId":{"type":"string","nullable":true,"description":"`null` clears it; changing the category without it clears it too.","format":"uuid"},"make":{"type":"string","nullable":true,"maxLength":100},"model":{"type":"string","nullable":true,"maxLength":100},"serialNo":{"type":"string","nullable":true,"maxLength":100},"year":{"type":"number","nullable":true,"minimum":1950,"maximum":2100},"purchaseValue":{"type":"string","nullable":true},"dayRate":{"type":"string","nullable":true,"description":"Applies to stays that start from now on; a stay under way keeps its rate."},"serviceIntervalDays":{"type":"number","nullable":true,"minimum":1,"maximum":3650},"nextServiceDate":{"type":"string","nullable":true,"format":"date"},"serviceVendorId":{"type":"string","nullable":true,"format":"uuid"}}},"EquipmentMovementDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string","example":"EQM-0021"},"movementType":{"enum":["ADDED","ISSUE","TRANSFER","RETURN","SERVICE_OUT","SERVICE_IN","STATUS_CHANGE"],"type":"string"},"statusFrom":{"nullable":true,"enum":["IN_STORE","ON_SITE","UNDER_REPAIR","OUT_OF_SERVICE","DISPOSED"],"type":"string"},"statusTo":{"enum":["IN_STORE","ON_SITE","UNDER_REPAIR","OUT_OF_SERVICE","DISPOSED"],"type":"string"},"from":{"type":"string","example":"Namanve Yard"},"to":{"type":"string","example":"Kampala Diesel Services"},"requisitionId":{"type":"string","nullable":true,"format":"uuid"},"requisitionNumber":{"type":"string","nullable":true},"movedOn":{"type":"string","format":"date"},"notes":{"type":"string","nullable":true},"movedByName":{"type":"string","nullable":true}},"required":["id","reference","movementType","statusFrom","statusTo","from","to","requisitionId","requisitionNumber","movedOn","notes","movedByName"]},"IssueEquipmentDto":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Today when omitted; never in the future."},"notes":{"type":"string","maxLength":1000},"projectId":{"type":"string","format":"uuid"},"requisitionId":{"type":"string","format":"uuid","description":"The requisition it answers."}},"required":["projectId"]},"TransferEquipmentDto":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Today when omitted; never in the future."},"notes":{"type":"string","maxLength":1000},"toStoreId":{"type":"string","format":"uuid"},"toProjectId":{"type":"string","format":"uuid"}}},"ReturnEquipmentDto":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Today when omitted; never in the future."},"notes":{"type":"string","maxLength":1000},"toStoreId":{"type":"string","format":"uuid","description":"The warehouse it comes back to."}},"required":["toStoreId"]},"ServiceOutDto":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Today when omitted; never in the future."},"notes":{"type":"string","maxLength":1000},"vendorId":{"type":"string","format":"uuid","description":"Who services it; the asset’s usual vendor when omitted."},"expectedReturnDate":{"type":"string","format":"date"}}},"ServiceInDto":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Today when omitted; never in the future."},"notes":{"type":"string","maxLength":1000},"toStoreId":{"type":"string","format":"uuid"},"backToSite":{"type":"boolean","description":"Return it to the project it was taken from."}}},"EquipmentStatusDto":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Today when omitted; never in the future."},"notes":{"type":"string","maxLength":1000},"reason":{"type":"string","maxLength":1000},"status":{"type":"string","enum":["OUT_OF_SERVICE","IN_STORE"],"description":"OUT_OF_SERVICE: not to be issued. IN_STORE: mark an out-of-service asset available."},"toStoreId":{"type":"string","format":"uuid","description":"Where it is kept: needed when it comes back from a vendor."}},"required":["reason","status"]},"DisposeEquipmentDto":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Today when omitted; never in the future."},"notes":{"type":"string","maxLength":1000},"reason":{"type":"string","maxLength":1000}},"required":["reason"]}}}}