Fluxo de upload

Neste guia será mostrado um fluxo completo de upload de arquivos no módulo PVA.

Visão geralCopiar link da seção

O módulo PVA aceita arquivos de texto dos SPEDs Fiscal, Contribuições e Contábil, além de arquivos zip cujo conteúdo seja um arquivo SPED dos tipos acima.

Todo upload no módulo PVA é composto por 3 etapas:

1. Geração das URLs para upload
2. Upload do arquivo ou das partes do arquivo
3. Finalização do upload

Um arquivo pode ser enviado em uma ou mais partes. Uma parte pode ter no máximo 5Gb. Portanto:

• Arquivos menores que 5Gb não precisam ser divididos em partes
• Arquivos maiores que 5Gb obrigatóriamente precisam ser divididos em partes
• Uma parte deve ter no mínimo 5Mb, exceto a última parte ou quando parte única

Fica a critério do utilizador da API dividir ou não o arquivo em partes. Para a grande maioria dos casos é possível realizar o upload com apenas uma parte. Entretanto, dividir o arquivo em partes tende a tornar o processo do upload mais rápido quando as partes são enviadas em paralelo.

Sugestão: Com exceção dos arquivos maiores do que 5Gb que devem ser particionados obrigatoriamente, iniciar a integração enviando apenas uma parte, e posteriormente implementar o envio em múltiplas partes para evitar problemas de performance no envio dos arquivos.

FluxoCopiar link da seção

Passo 1: Gerar URLsCopiar link da seção

Utilizamos o endpoint de Passo 1: Gerar URLs. Nesse endpoint são especificados em quantas partes o arquivo será enviado.

Por exemplo, consumindo o endpoint como

/api/pva/upload/createUrl/1

irá gerar uma lista com uma URL. As URLs devem ser utilizadas na sequência em que foram retornadas. Então se foram retornadas 2 URLs, a primeira parte do arquivo deve ser enviada usando a URL de índice zero e a segunda parte do arquivo deve ser enviada usando a URL de índice 1.

Além disso, é necessário armazenar em memória os atributos objectKey e uploadId, que serão utilizados no último passo do upload.

É muito importante especificar neste endpoint o header http de request Content-Type com os valores text/plain para texto ou application/zip para zip.

Passo 2: Upload das partesCopiar link da seção

Utilizamos o endpoint de [POST URL_RETORNADA_EM_PASSO_1].

Devemos enviar no corpo da requisição de cada URL o conteúdo em bytes da sua parte correspondente. Se foi gerado apenas uma URL deve ser enviado todo o conteúdo do arquivo.

Em caso de sucesso, este endpoint irá retornar no response header ETag um valor que também deve ser armazenado para uso no último passo do upload. Armazene em uma lista ou array de maneira o índice de um valor ETag seja correspondente ao índice da URL utilizada.

Passo 3: Finalizar UploadCopiar link da seção

Utilizamos o endpoint de Passo 3: Finalizar upload.

Aqui iremos enviar como parâmetro no endpoint os valores salvos de objectKey e uploadId do passo 1.

Além disso, no body da request devemos enviar a lista de ETags salvos no passo 2 juntamente com o número da sua parte.

Este endpoint também possui um atributo no corpo chamado fileName. Este atributo irá associar um nome à escrituração enviada, como por exemplo SPED_CONTRIB_122023.txt. Este nome será usado tanto em consultas em outros endpoints bem como para nomear os arquivos de recibo após a transmissão.

Exemplo do fluxoCopiar link da seção

Passo 1: Gerando as URLsCopiar link da seção

Parâmetros:

Headers:

Salvamos em memória os valores de objectKey e uploadId. Também setamos o header Content-Type para text/plain.

Passo 2: Realizando o uploadCopiar link da seção

Realiza o upload das partes. Neste caso é apenas uma parte.

Passo 3: Finalizando o uploadCopiar link da seção

Parâmetros:

Headers:

Finalizamos o upload usando os valores salvos nos passos anteriores.

Lembrando que em caso de dúvidas sobre o que significa cada parâmetro e campo de retorno, consultar a referência de API.