Contract API Changes

New Status: signing

Added signing status to the contract lifecycle.

Status transitions

signature → signing → completed

• signature: configuring signatures (can add/remove internal signers)
• signing: signatures in progress (cannot add/remove internal signers)

step-engine updates

• THIRD_PARTY_STATUSES: includes signing
• STATUS_ORDER: [..., 'signature', 'signing', 'completed']
• STATUS_TO_STEP: { signing: 'signature' }

---

New Endpoints

Download individual document file

GET /contracts/:id/documents/:docId/download
Response: blob (application/pdf)

Download all provider documents as ZIP

GET /contracts/:id/providers/:providerId/documents/download
Response: blob (application/zip)

---

History Action Mapping

The backend must record history entries automatically when the corresponding endpoint is called.

Entry format

{
  "id": "uuid",
  "entityType": "contract",
  "entityId": "contract-uuid",
  "action": "part_added",
  "data": "Added provider 'Company XYZ' as provider",
  "metadata": {
    "partName": "Company XYZ",
    "partRole": "provider"
  },
  "updatedBy": "user-uuid",
  "updatedByName": "User Name",
  "updatedAt": "2026-02-10T12:00:00Z"
}

Action → Endpoint mapping

Action	Endpoint	Data to record
contract_created	POST /contracts	Contract name, selected workflow
contract_updated	PUT /contracts/:id	Changed fields (diff)
title_changed	PUT /contracts/:id (when name changes)	Previous name → new name
status_changed	PATCH /contracts/:id/status	Previous status → new status
part_added	POST /contracts/:id/parts	Part name, role (borrower/provider/etc)
part_removed	DELETE /contracts/:id/parts/:partId	Removed part name
template_selected	PUT /contracts/:id (when templateId changes)	Selected template name
variable_assigned	PUT /contracts/:id (when variableValues changes)	Variable name, assigned value
document_added	PUT /contracts/:id (when documentRequirements grows)	Added document name
document_removed	PUT /contracts/:id (when documentRequirements shrinks)	Removed document name
step_completed	PATCH /contracts/:id/steps/:key/complete	Completed step name
sent_to_review	PATCH /contracts/:id/status (→ in_review)	Number of reviewers
review_comment_added	POST /contracts/:id/review/:itemId/comment	Comment text, contract item
review_comment_edited	PATCH /contracts/:id/review/:itemId/comments/:commentId	Previous text → new text
review_item_approved	PATCH /contracts/:id/review/:itemId/approve	Item name, who approved
review_item_rejected	PATCH /contracts/:id/review/:itemId/reject	Item name, rejection reason
reviewer_added	POST /contracts/:id/review/reviewers	Reviewer name, email
reviewer_removed	DELETE /contracts/:id/review/reviewers/:id	Removed reviewer name
reviewer_reminder_sent	POST /contracts/:id/review/reviewers/:id/reminder	Notified reviewer name
file_uploaded	POST /contracts/:id/documents/:docId/files	File name, document, provider
file_deleted	DELETE /contracts/:id/documents/:docId/files/:fileId	Removed file name
upload_approved	PATCH /contracts/:id/documents/:docId/review (approved)	Document name, provider
upload_rejected	PATCH /contracts/:id/documents/:docId/review (rejected)	Document name, reason
provider_reminder_sent	POST /contracts/:id/providers/:id/reminder	Notified provider name
signature_config_saved	PUT /contracts/:id/signatures	Number of groups, number of signers
signature_started	POST /contracts/:id/signatures/start	Number of notified signers
signer_signed	POST /contracts/:id/signatures/:signerId/sign	Signer name
signer_rejected	POST /contracts/:id/signatures/:signerId/reject	Name, rejection reason
signer_reminder_sent	POST /contracts/:id/signatures/:signerId/reminder	Notified signer name
contract_archived	PATCH /contracts/:id/status (→ archived)	Who archived
contract_cancelled	PATCH /contracts/:id/status (→ cancelled)	Who cancelled
contract_completed	PATCH /contracts/:id/status (→ completed)	Completion date
contract_deleted	DELETE /contracts/:id	Who deleted

---

Contract Validity (Vigência)

The contract toolbar includes a validity date range (start date / end date) that defines the contract's effective period.

Fields

• startDate (ISO 8601 string, required): contract validity start date
• endDate (ISO 8601 string, required): contract validity end date

Both fields are required when creating a contract, just like the contract name.

API

Validity dates are saved via PUT /contracts/:id with startDate and endDate fields. The frontend debounces changes (1 second) before sending.

UI Behavior

• Date range picker in the toolbar between title/workflow and progress
• Disabled when contract is in a terminal status (completed, cancelled, archived)
• The date range is required and cannot be cleared

History action

Action	Endpoint	Data to record
validity_changed	PUT /contracts/:id (when startDate/endDate changes)	Previous range → new range

---

HistoryEntry type updates

Added optional fields to src/domain/history/types.ts:

• action?: string, action identifier from the table above
• metadata?: Record<string, unknown>, structured data about the action
• updatedByName?: string, display name of the user who performed the action