Lock/Unlock Endpoints

/api/partner/1.0/{product}/documents/{documentId}/lock (POST)

Endpoint authentication

When adopting OAuth 2.0 as an authentication method, the below security requirements are needed in order to trigger this endpoint:

• The user must fulfill the below security roles requirements; if he fails to obtain access to all the necessary security roles, an error 403: Insufficient privileges to execute this request is returned:

  • The user must acquire access to at least one of the following security roles; he needs to have access to the security role corresponding to the product included in the URL:

    • Tax – Access T1 Product

    • Tax – Access T2 Product

    • Tax – Access T3 Product

    • Tax – Access Forms Product

  • In addition, the user cannot lock a document if he does not have access to the below security role:

    • Tax – Returns – Lock and unlock

• This endpoint validates against the user’s contact security and document visibility. If the user does not have access to the document provided in the URL or the contact associated to this document, an error 404: Resource not found in the system is returned.

Endpoint description

Locks a document in the product specified in the URL of the endpoint. Once the lock is initiated, a taskID is provided in the response location header and the status of the task can be retrieved by using the Task endpoint.

Model	N/A
Properties	N/A

Examples

Request URL	https://mysite.cchifirm.ca/taxcan/api/partner/1.0/T1/documents/221e7400-8d38-432e-a3ac-c988dfc6dc05/lock
Request body	N/A
Response body	N/A

Note: Locking an already locked document will result in receiving a 200 OK instead of the expected 202 accepted.

/api/partner/1.0/lock/{resultId} (GET)

Endpoint description

Returns the result of a lock process. An ID must be provided in the URL, which represents the resource of the lock that was completed. This ID is provided by the Tasks endpoint.

Model	N/A
Properties	N/A

Examples

Request URL	https://mysite.cchifirm.ca/taxcan/api/partner/1.0/lock/f3eb4d73-208b-4688-a0a0-99a954b2df25
Request body	N/A
Response body	{ "errors": [] }

/api/partner/1.0/{product}/documents/{documentId}/unlock (POST)

Endpoint authentication

When adopting OAuth 2.0 as an authentication method, the below security requirements are needed in order to trigger this endpoint:

• The user must fulfill the below security roles requirements; if he fails to obtain access to all the necessary security roles, an error 403: Insufficient privileges to execute this request is returned:

  • The user must acquire access to at least one of the following security roles; he needs to have access to the security role corresponding to the product included in the URL:

    • Tax – Access T1 Product

    • Tax – Access T2 Product

    • Tax – Access T3 Product

    • Tax – Access Forms Product

  • In addition, the user cannot unlock a document if he does not have access to the below security role:

    • Tax – Returns – Lock and unlock

• This endpoint validates against the user’s contact security and document visibility. If the user does not have access to the document provided in the URL or the contact associated to this document, an error 404: Resource not found in the system is returned.

Endpoint description

Unlocks a document in the product specified in the URL of the endpoint.

Model	N/A
Properties	N/A

Examples

Request URL	https://mysite.cchifirm.ca/taxcan/api/partner/1.0/T1/documents/221e7400-8d38-432e-a3ac-c988dfc6dc05/unlock
Request body	N/A
Response body	{ "errors": [] }