Upload flow

This guide shows a complete file upload flow in the PVA module.

OverviewCopy Anchor Link

The PVA module accepts text files of the Fiscal, Contribuições and Contábil SPEDs, as well as zip files whose content is a SPED file of the types above.

Every upload in the PVA module consists of 3 stages:

1. Generation of the upload URLs
2. Upload of the file or of the file parts
3. Completion of the upload

A file can be sent in one or more parts. A part can be at most 5Gb. Therefore:

• Files smaller than 5Gb do not need to be split into parts
• Files larger than 5Gb must be split into parts
• A part must be at least 5Mb, except for the last part or when there is a single part

It is up to the API user whether or not to split the file into parts. In the vast majority of cases, the upload can be done with a single part. However, splitting the file into parts tends to make the upload faster when the parts are sent in parallel.

Suggestion: Except for files larger than 5Gb, which must be partitioned, start the integration by sending a single part, and later implement multipart upload to avoid performance issues when sending files.

FlowCopy Anchor Link

Step 1: Generate URLsCopy Anchor Link

We use the Step 1: Generate URLs endpoint. In this endpoint you specify how many parts the file will be sent in.

For example, calling the endpoint as

/api/pva/upload/createUrl/1

will generate a list with one URL. The URLs must be used in the order in which they were returned. So if 2 URLs were returned, the first part of the file must be sent using the URL at index zero and the second part of the file must be sent using the URL at index 1.

In addition, you must store in memory the objectKey and uploadId attributes, which will be used in the last step of the upload.

It is very important to specify in this endpoint the Content-Type HTTP request header with the value text/plain for text or application/zip for zip.

Step 2: Upload the partsCopy Anchor Link

We use the [POST URL_RETORNADA_EM_PASSO_1] endpoint.

In the request body for each URL, we must send the byte content of its corresponding part. If only one URL was generated, the entire file content must be sent.

On success, this endpoint will return in the ETag response header a value that must also be stored for use in the last step of the upload. Store it in a list or array so that the index of each ETag value corresponds to the index of the URL used.

Step 3: Complete UploadCopy Anchor Link

We use the Step 3: Complete upload endpoint.

Here we send as endpoint parameters the objectKey and uploadId values saved in step 1.

In addition, in the request body we must send the list of ETags saved in step 2 together with their part numbers.

This endpoint also has a body attribute called fileName. This attribute associates a name with the uploaded bookkeeping, for example SPED_CONTRIB_122023.txt. This name will be used both in queries on other endpoints and to name the receipt files after transmission.

Flow exampleCopy Anchor Link

Step 1: Generating the URLsCopy Anchor Link

Parameters:

Headers:

We save the objectKey and uploadId values in memory. We also set the Content-Type header to text/plain.

Step 2: Performing the uploadCopy Anchor Link

Upload the parts. In this case there is only one part.

Step 3: Completing the uploadCopy Anchor Link

Parameters:

Headers:

We complete the upload using the values saved in the previous steps.

Remember that if you have any questions about the meaning of each parameter and response field, consult the API reference.