Migração V1 → V2

Guia para sistemas legados que ainda dependem da V1 da API E-Docs.

V1 descontinuada

A API V1 do E-Docs não deve mais ser utilizada. Toda nova integração e toda atualização de sistema legado devem adotar a V2.

Por que migrar

A V1 não recebe mais correções nem novas funcionalidades.
A V2 introduziu mudanças de infraestrutura (armazenamento em MinIO/S3) que alteram o fluxo de upload.
Apenas a V2 garante compatibilidade com novos recursos (ex.: novos atos processuais e fluxos de assinatura).

Aspecto	V1 (legado)	V2 (vigente)
Base URL (Treinamento)	endpoints `/v1/...`	`https://api.treinamento.e-docs.es.gov.br` (`/v2/...`)
Upload de arquivo	parte do mesmo POST de captura	2 etapas separadas: gerar URL + enviar arquivo direto ao MinIO/S3
Endpoint de geração de URL	(interno à captura)	`GET /v2/documentos/upload-arquivo/gerar-url-upload/{tamanhoArquivo}`
Ordem do upload	arquivo enviado junto aos metadados	arquivo enviado antes do registro; `idArquivo` é referenciado depois
Padrão assíncrono	retorno imediato (síncrono) em algumas operações	atos de escrita retornam `202 Accepted` + `idEvento` (polling em `GET /v2/eventos/{idEvento}`)
Escopos OAuth	escopos legados	escopos V2: `api-sigades-consultar`, `api-sigades-documento`, `api-sigades-encaminhamento`, `api-sigades-processo` (veja Autenticação)

Auditar pontos de chamada à V1 no seu sistema (todas as URLs /v1/...).
Atualizar autenticação: revisar os escopos solicitados ao Acesso Cidadão (veja a tabela em Autenticação).
Refatorar o fluxo de upload seguindo as duas etapas: gerar URL → enviar arquivo. Detalhes e exemplo em Documentos.
Adotar o padrão assíncrono: tratar 202 Accepted + polling em /v2/eventos/{idEvento}.
Validar restrição de acesso: o objeto RestricaoAcessoApiEntry é obrigatório nos registros — confira Restrição de Acesso.
Testar em Treinamento ponta a ponta antes de promover para Produção.

Enviar o arquivo antes de obter a URL: a URL é assinada e específica para o tamanho informado.
Esquecer de aguardar o evento: ler idEvento e seguir adiante imediatamente sem fazer polling leva a estados inconsistentes no integrador.
Reuso indevido de idArquivo: o idArquivo retornado pela geração de URL é vinculado a um único registro. Após captura, gere um novo upload se for um novo documento.
Escopos insuficientes: tokens emitidos com escopos da V1 não funcionam em V2. Revise a app no Acesso Cidadão.

Abra atendimento pelo canal oficial do PRODEST / E-Flow informando o sistema (slug no Acesso Cidadão), ambiente e endpoints em uso.
Inclua o traceId retornado em respostas de erro — facilita a investigação.