Pular para o conteúdo principal

Download and list documents

Download document versions​

Once a document has been created, it is possible to download different versions of it, according to the stage it is in. Use the Document Download API, providing the desired type in the type parameter:

GET /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11/content?type=Original

Version types (type)​

typeDescription
OriginalOriginal uploaded file
SignaturesSigned file
PrinterFriendlyVersionPrinter friendly version
SigningTagsSigning tags
SignatureMarksSignature marks
OriginalWithMarksOriginal file with the signature marks
SignaturesManifestSignatures manifest
Return format

There are two methods with different return types: one returns the document as a Stream of data and the other returns the document as a vector of bytes[].

In the client libraries:

ClientThe file (GET .../content)Other forms
C#GetDocumentContentAsync(id, DocumentDownloadTypes), a StreamGetDocumentContentBytesAsync(id, DocumentDownloadTypes), a DocumentContentModel (Base64); GetDocumentBytesAsync(id, DocumentTicketType), a byte[]
JavagetDocumentContent(id, DocumentDownloadTypes), an InputStreamgetDocumentBytes(id, DocumentTicketType), a byte[]
Node.jsapiDocumentsIdContentGet(id, DocumentDownloadTypes, { responseType: "arraybuffer" }). Without responseType: "arraybuffer", axios decodes the file as text and corrupts itapiDocumentsIdContentB64Get(id, DocumentDownloadTypes), the bytes in Base64
PHPgetDocumentContent($id, DocumentDownloadTypes::...), the file's contentGetDocumentContentBytesAsync($id, DocumentDownloadTypes::...), the content-b64 JSON, with the bytes in Base64

The DocumentDownloadTypes of the PHP client 1.4.10 has no constant for SignaturesManifest. getDocumentContent puts the type in the query string as it gets it, so pass the text "SignaturesManifest".

When a version cannot be downloaded​

  • Signatures and PrinterFriendlyVersion exist only after at least one participant has signed. For a document nobody has signed yet, the API answers 422 with the error code DocumentHasNoSignatures. Until the document is Concluded, Signatures holds the signatures collected so far.
  • Canceled, expired or refused documents can only be downloaded as Original and PrinterFriendlyVersion.

Before downloading, read the document with the Document Details API and check its hasSignature and status fields, as the samples do. See Error responses for the format of the error.

With a client library, read the document, check its status, then download Signatures and PrinterFriendlyVersion: 

using Lacuna.Signer.Api;

// 1. Check the status
var details = await signerClient.GetDocumentDetailsAsync(documentId);
// details.IsConcluded: the whole flow is done
// details.FlowActions[i].Status == ActionStatus.Completed: that participant is done
if (!details.HasSignature)
{
    return; // only Original can be downloaded yet
}

// 2. Signatures: the signed file. Not for canceled, refused or expired documents.
if (details.Status != DocumentStatus.Canceled && details.Status != DocumentStatus.Refused && details.Status != DocumentStatus.Expired)
{
    using (var signed = await signerClient.GetDocumentContentAsync(documentId, DocumentDownloadTypes.Signatures))
    using (var fileStream = new FileStream("signed.pdf", FileMode.Create, FileAccess.Write))
    {
        signed.CopyTo(fileStream);
    }
}

// 3. PrinterFriendlyVersion: a PDF with the signature marks and a signatures manifest
using (var printerFriendly = await signerClient.GetDocumentContentAsync(documentId, DocumentDownloadTypes.PrinterFriendlyVersion))
using (var fileStream = new FileStream("printer-friendly.pdf", FileMode.Create, FileAccess.Write))
{
    printerFriendly.CopyTo(fileStream);
}

The client is created as in Create documents. In production, learn that a document changed through webhooks instead of polling its details.

How each client reports the error, when you call it without checking first:

  • C#: GetDocumentContentAsync throws a SignerApiException.
  • Java: getDocumentContent throws a RestUnreachableException for any HTTP error, without the status code or the error code, so check the document first. The other methods throw a RestErrorException, whose getStatusCode(), getErrorCode() and getErrorMessage() give the status and the ErrorModel's code and message.
  • Node.js: the promise is rejected with the axios error; error.response.status has the status and error.response.data the ErrorModel (with responseType: "arraybuffer", as bytes).
  • PHP: getDocumentContent does not throw, as the warning below explains.
PHP client

In the PHP client, getDocumentContent does not throw an exception on HTTP errors: it returns the body of the error response, the ErrorModel JSON, as if it were the file. Saved without a check, it becomes a "file" that holds the error. Check the document first, as above.

Examples on GitHub: C# · Java · PHP · Node.js

List documents​

It is possible to list documents according to different patterns and needs. The available parameters are described in the Document Listing API. Among the possible listing types:

  • Pending documents for a particular participant
  • Concluded documents
  • List by folders
  • List by organizations

Filter by status​

The status parameter filters by document status: Pending, Paused, Concluded, Refused, Canceled, Expired, PendingOrRefused or CanceledOrExpired. The Pending value also returns paused documents. To list only paused documents, use Paused.

Filter by participant​

To list a participant's documents, send two parameters together:

ParameterDescription
participantQThe text to search for, for example the participant's CPF or e-mail.
participantQueryTypeWhere to search for the text: Name, Identifier, Email or Phone.

Without both parameters, the Signer does not filter by participant. Available from version 3.0.0, the participantSituation parameter filters by the situation of the participant's action:

ValueDocuments listed
PendingThe participant still has to act, and the document is in progress or paused.
CompletedThe participant has already acted: signed, approved or refused.

Without participantSituation, the list returns every situation.

GET /api/documents?participantQ=81976153069&participantQueryType=Identifier&participantSituation=Pending

Folders​

To list the folders of the API key's organization, use GET /api/folders. The q parameter searches by name, and parentId with filterByParent=true lists a folder's subfolders. To list the documents in a folder, use the folderId parameter of GET /api/documents.

The web interface uses GET /api/folders/search to search the folders the user can access in all organizations. This route does not accept an API key.

Examples on GitHub: C# · Java · PHP · Node.js

View as Markdown