Basic document creation

Updated date: 07/07/2026
Updated by: VNPT eContract's team

---

Describes the basic document creation workflow when integrating the organization’s management system with VNPT eContract.
If the customer’s system has already generated the document file (.docx or .pdf) — and all editing or content preparation is performed entirely outside of VNPT eContract — the organization only needs to use this file and follow the processing steps below.

Use this guide when the customer system is responsible for preparing the document content and VNPT eContract is responsible for storing the document, routing it to processors, collecting signatures/approvals, and returning the processing status.

Before integration

Prepare the following information before calling the document creation APIs:

Item	Description
Account and token	API account used to call the login API and obtain a Bearer token.
Document file	The final document content prepared by the customer system. If using the v1 create document API, upload the file format accepted by that API, typically PDF according to the API detail page.
Document metadata	no, subject, typeId, departmentId, and optional information such as description, customerCode, customerInformation, attachments, or related documents.
Workflow participants	User codes of all processors who will view, approve, e-sign, digitally sign, draw-sign, fill data, or coordinate the document.
Signing positions	Required when the workflow uses fixed signing positions. Prepare pageSign and position in the format required by the update process API.
Synchronization strategy	Decide whether the customer system will poll the document list API to synchronize status, histories, and the latest document information.

Process flow

Process Explanation

• The customer’s management system generates the document file in .docx or .pdf format.
• Call the login (1) API to authenticate and obtain an access token for subsequent operations.
• Call the document type list and department list APIs to retrieve the document type ID and department ID.
• Call the create document (3) API to create a new document and obtain the document ID (4).
• Call the update document process (5) API to define the processing workflow (including processing steps and assigned users).
• After updating the workflow, call the send document process (7) API. The system will validate the workflow, notify the assigned processor (8), and return the waitingProcess information of the next processor.
• Each user in the workflow will receive notifications via email/SMS/application and perform the required document action (approval, e-signature, digital signature) (10 + 11). The system processes the signature, updates the status, and moves to the next user, repeating until the final step is completed.
• Call the document list API to retrieve the document status (15), processing history, and related information. This data can optionally be synchronized back to the customer’s management system.

API sequence for developers

Step	API	Input to prepare	Output to keep / next action
1	Login	API username/password.	Store the access token and send it as Bearer token in the next requests.
2	Document type list and department list	No document data yet; use these APIs to look up master data.	Use typeId and departmentId when creating the document.
3	Create document	Document file and metadata such as no, subject, typeId, departmentId.	Store data.id as the document ID. The document is created but is not sent to processors yet.
4	Update document process	Document ID, processInOrder, fixedPosition, and processes.	Confirm the returned processes are correct before sending.
5	Send document process	Document ID.	Document status changes to processing; use waitingProcess to identify the current waiting processor.
6	Process document	waitingProcess.id, action data, OTP when required, signing position/signature data when required.	If another step remains, the response returns the next waitingProcess; repeat until completion.
7	Document list	Search/filter parameters such as document code, status, or created date.	Synchronize document status, histories, and download information back to the customer system if needed.

Important integration notes

Topic	Guidance
Document number	no should be unique in the customer integration flow so the customer system can reconcile records with VNPT eContract.
Create vs send	Creating a document only stores the document and metadata. Processors are notified only after calling the send process API.
waitingProcess.id	The process document API requires the current waitingProcess.id, not the document ID. Get it from the send process response, process response, document list, or processing-code login flow.
Sequential workflow	If processInOrder is true, the next user can process only after the previous user completes their step.
Non-sequential workflow	If processInOrder is false, multiple users may be able to process in parallel depending on the configured workflow.
Signing coordinates	For fixed signing positions, position uses rectangle coordinates and pageSign identifies the signing page.
OTP processing	Some signing/approval actions require two calls: the first call requests OTP, and the second call confirms using the OTP received via email/SMS.
Status synchronization	If the customer system needs near real-time status, design a polling or synchronization job using document status and document code.

Recommended implementation checklist

• Create and store a mapping between the customer system record ID, document no, and VNPT eContract data.id.
• Validate that the document file can be opened and has the final page count before calculating signing coordinates.
• Validate typeId, departmentId, and all processedByUserCode values before sending the workflow.
• Store the latest document status and waitingProcess after each send/process/list response.
• Handle OTP-required responses separately from completed process responses.
• Log API request IDs, document ID, document number, and error messages for operation support.

caution

• The above flow omits interactions between VNPT eContract and digital signing systems, HSM, authentication systems, etc.
• Depending on the unit’s operations, the Document Processing Call step (10 - 11) may vary: the user might interact directly with VNPT eContract without going through a 3rd System (in cases where the user uses VNPT eContract’s web view for signing).
• The Document List Call step (15) may be optional, depending on the unit’s data synchronization purposes.