Pular para o conteúdo principal

Documentos

Endpoints para registro, captura e gestão de documentos digitais.

Esquemas canônicos

Os exemplos de JSON nesta página são ilustrativos. Os esquemas oficiais (com todos os campos e validações) estão no Swagger V2.

Um documento contém informações acerca de um documento em si, além de englobar o arquivo relativo a esse documento.

Tipos de Assinatura (Lei Nº 14.063/20)​

  • Assinatura Eletrônica (ou Assinatura Eletrônica Avançada): A assinatura realizada diretamente pelo E-Docs.
  • Assinatura Digital (ou Assinatura Eletrônica Qualificada): Uma assinatura ICP-Brasil realizada diretamente no arquivo texto, previamente à sua captura no E-Docs.
  • Sem Assinatura: O arquivo pode ainda não conter nenhuma assinatura.

Procedimento Padrão para Registrar Documentos​

Fluxo Assíncrono

As ações de captura utilizam uma fila de eventos:

  1. O endpoint retorna um idEvento (status 202 Accepted).
  2. Consulte GET /v2/eventos/{idEvento} para verificar quando a captura foi concluída.
  3. Após processado, o evento retornará o identificador do documento capturado.
  • 1 - Autenticação:
  • 2 - Envio de Arquivo para E-Docs:
    • a. Enviar para o E-Docs o tamanho do arquivo a ser enviado, recebendo o endereço para onde deve ser enviado o arquivo físico;
    • b. Enviar o arquivo para o caminho acima (esse envio não será realizado através de endpoint E-Docs), recebendo um objeto JSON com informações para as etapas posteriores.
  • 3 - Registro do documento e captura:
    • Se for arquivo nato-digital e com Assinatura Eletrônica E-Docs:
      • O documento deverá passar pela Fase de Assinatura, onde o Capturador (cidadão ou servidor responsável) informará o identificador do arquivo criado na nuvem (do JSON recebido anteriormente), metadados e quais serão os assinantes.
      • Todos os assinantes devem se manifestar (assinar ou recusar).
      • Após o último assinante, o documento é enviado para captura, retornando um identificador do evento.
    • Se for arquivo nato digital e com apenas a Assinatura Eletrônica E-Docs do Capturador:
      • O Capturador informará o identificador do arquivo (nuvem) e metadados.
      • O documento será assinado pelo capturador, enviado para captura e será retornado um identificador do evento.
    • Para todos os outros casos:
      • O Capturador informará o identificador do arquivo (nuvem) e metadados.
      • O documento será enviado para captura, sendo retornado um identificador do evento.
  • 4 - Captura do documento:
    • O E-Docs enfileira o documento em um objeto de evento.
    • Uma vez executado, o objeto será complementado com o identificador do documento capturado.
  • 5 - Documento capturado:
    • O documento já pode ser utilizado em processos, encaminhamentos, consultas, etc.

Autenticação​

Utilize um Bearer Token obtido via Acesso Cidadão. Consulte a documentação de Autenticação para detalhes.

  • Fase de Assinatura e Captura: escopo api-sigades-documento.
  • Consultas: escopo api-sigades-consultar.

Envio de Arquivo para E-Docs​

A API aceita apenas arquivos PDF. Áudio e vídeo estão disponíveis exclusivamente pela interface web do E-Docs. O tamanho máximo permitido é 250MB.

O processo envolve dois passos:

  1. Chamar GET /v2/documentos/upload-arquivo/gerar-url-upload/{tamanhoArquivo} informando o tamanho em bytes — a resposta retorna a URL de destino e os parâmetros necessários para o envio.
  2. Realizar um POST direto para essa URL com o arquivo — este envio não passa pelo endpoint do E-Docs.

Passo 1 — Gerar URL de upload​

Requisição

GET /v2/documentos/upload-arquivo/gerar-url-upload/{tamanhoArquivo}
Authorization: Bearer {token}

Resposta (200 OK) — exemplo ilustrativo:

{
  "url": "https://minio.e-docs.es.gov.br/edocs-tmp/...",
  "body": {
    "key": "edocs-tmp/abc123/arquivo.pdf",
    "policy": "...",
    "x-amz-credential": "...",
    "x-amz-signature": "..."
  },
  "idArquivo": "8f9a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c"
}

O idArquivo é o que será informado nos passos seguintes (registro/captura/assinatura).

Passo 2 — Enviar o arquivo físico​

POST multipart/form-data para a url retornada, repassando todos os campos de body + o arquivo binário no campo file. Retorno esperado: 204 No Content.

Exemplo de implementação (C#)​

// Modelo para o JSON recebido no endpoint de geração de URL
class UploadDataJsonModel
{
    public UploadDataJsonModel(string caminhoCompletoArquivoLocal, DocumentoArquivoApiModel json)
    {
        Url = json.Url;
        File = caminhoCompletoArquivoLocal;
        Body = json.Body;
    }
    [JsonProperty("file")] public string File { get; set; }
    [JsonProperty("url")] public string Url { get; set; }
    [JsonProperty("body")] public IDictionary<string, string> Body { get; set; }
}

// Método de POST (realizar imediatamente após obter a URL)
// Observação: Este é um exemplo simplificado, considere as recomendações da Microsoft (https://docs.microsoft.com/pt-br/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests) para utilização de HttpClient.
public async Task<bool> UploadFileToUrl(UploadDataJsonModel data) {
    // cria o cliente do request
    using var client = new HttpClient();
    client.DefaultRequestHeaders.Add("Accept", "application/json");

    // adiciona os parâmetros retornados pelo JSON no content
    using var content = new MultipartFormDataContent();
    data.Body.ToList().ForEach(parametro => content.Add(new StringContent(parametro.Value), parametro.Key));

    // cria o content com o arquivo
    var arquivo = File.ReadAllBytes(data.File).ToArray();
    using MemoryStream memoryStream = new MemoryStream(arquivo);
    using StreamContent streamContent = new StreamContent(memoryStream);
    streamContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/octet-stream");
    streamContent.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data") { 
        Name = "file", // nome do parâmetro do arquivo, não alterar
        FileName = data.File.Split('\\')[^1] // na prática esse nome aqui não será utilizado
    };
    // o arquivo deve ser o último parametro do content, visto que é o arquivo que será enviado e validado pelo MinIO/S3
    content.Add(streamContent);

    // faz a requisição
    using var response = await client.PostAsync(data.Url, content);
    return response.IsSuccessStatusCode;
}

Nota: O retorno é um status 204 No Content.

Esse arquivo ficará em área temporária. Caso o próximo passo (registro dos metadados) não seja realizado, o arquivo será excluído por falta de vínculo.

Documentação completa dos métodos

Recursos Auxiliares​