Documentos
Integração via API - Documentos
A documentação para os métodos de Documentos pode ser vista aqui.
Um documento contém informações acerca de um documento em si, além de englobar o arquivo relativo a esse documento.
Ele pode ser assinado das formas abaixo (Lei Nº 14.063/20 - Art. 4º):
- 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.
- O arquivo pode ainda não conter ter nenhuma assinatura
O procedimento padrão para registrar documentos no E-Docs consistem em:
- 1 - Autenticação no E-Docs:
- Autenticar para uso do E-Docs por método Bearer;
- 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:
- a - O documento deverá passar pela Fase de Assinatura, onde o Capturador (o cidadão ou servidor responsável pelo registro) informará o identificador do arquivo criado na nuvem constante no JSON recebido na etapa anterior e todas as informações de metadados e quais serão os assinantes para o mesmo;
- b - Todos os assinantes devem se manifestar (assinar ou recusar assinatura);
- c - Após o último assinante se manifestar, o documento será enviado para captura, sendo retornado um identificador do evento dessa captura;
- Se for arquivo nato digital e com apenas a Assinatura Eletrônica E-Docs do Capturador:
- a - O Capturador (o cidadão ou servidor responsável pelo registro) informará o identificador do arquivo criado na nuvem constante no JSON recebido na etapa anterior e todas as informações de metadados;
- b - O documento será assinado pelo capturador e posteriormente o documento será enviado para captura, sendo retornado um identificador do evento dessa captura;
- Para todos os outros casos:
- a - O Capturador (o cidadão ou servidor responsável pelo registro) informará o identificador do arquivo criado na nuvem constante no JSON recebido na etapa anterior e todas as informações de metadados;
- b - O documento será enviado para captura, sendo retornado um identificador do evento dessa captura;
- Se for arquivo nato-digital e com Assinatura Eletrônica E-Docs:
- 4 - Captura do documento:
- a - O E-Docs irá colocar o documento na fila de captura, em um objeto de evento, com o identificador recebido na etapa anterior;
- b - Uma vez o evento seja executado, o objeto de evento será complementado com a informação do identificador do documento capturado;
- 5 - Documento capturado:
- O documento já pode ser utilizado em processos, encaminhamentos, consultas, etc.
Autenticação no E-Docs
A autenticação será através do padrão Bearer Token, utilizando o Access Token obtido através da Autenticação de Usuário no Acesso Cidadão.
- Para as requisições aos endpoints de Fase de Assinatura e Captura será requerido o scope 'api-sigades-documento' no cabeçalho;
- Para as requisições de consulta, será requerido o scope 'api-sigades-consultar' (ou a anterior) no cabeçalho.
Envio de Arquivo para E-Docs
A API do E-Docs aceita apenas arquivos texto, de extensão PDF.
O primeiro endpoint a ser utilizado é o Gerar URL para upload, onde deve ser enviado o tamanho exato do arquivo a ser enviado, recebendo ao final uma url que será utilizada para o envio do arquivo físico.
De posse desse endereço, deve-se realizar uma requisição POST direto para a nuvem do E-Docs, conforme exemplos de código abaixo.
Primeiro criar um modelo que vai conter o JSON recebido no endpoint anterior e o caminho completo do arquivo no servidor local:
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; }
}
Agora o método para realizar a requisição POST (essa etapa deve ser realizada imediatamente após a execução da etapa anterior, pois a janela de envio se fecha em poucos segundos)
Observação: Este é um exemplo simplificado, considere as recomendações da Microsoft 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");
//adiviona 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 últo 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);
//se tudo der certo vai retornar true
return response.IsSuccessStatusCode;
}
obs: o retorno do post não será um retorno de status 200 com conteúdo como é costumeiro, será apenas um retorno de status 204 No Content (sem conteúdo).
Esse arquivo irá para uma área temporária aguardando os próximos passos de registro dos metadados do Documento. Caso não seja realizado esse próximo passo, esse arquivo será excluído do servidor, por falta de vínculo com um Documento registrado no E-Docs.
Após enviar o documento para a nuvem, o próximo passo é registrar o documento no E-Docs realizando uma Captura.Integração via API - Documentos
A documentação para os métodos de Documentos pode ser vista aqui.
Um documento contém informações acerca de um documento em si, além de englobar o arquivo relativo a esse documento.
Ele pode ser assinado das formas abaixo (Lei Nº 14.063/20 - Art. 4º):
- 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.
- O arquivo pode ainda não conter ter nenhuma assinatura
O procedimento padrão para registrar documentos no E-Docs consiste em:
- 1 - Autenticação no E-Docs:
- Autenticar para uso do E-Docs por método Bearer;
- 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:
- a - O documento deverá passar pela Fase de Assinatura, onde o Capturador (o cidadão ou servidor responsável pelo registro) informará o identificador do arquivo criado na nuvem constante no JSON recebido na etapa anterior e todas as informações de metadados e quais serão os assinantes para o mesmo;
- b - Todos os assinantes devem se manifestar (assinar ou recusar assinatura);
- c - Após o último assinante se manifestar, o documento será enviado para captura, sendo retornado um identificador do evento dessa captura;
- Se for arquivo nato digital e com apenas a Assinatura Eletrônica E-Docs do Capturador:
- a - O Capturador (o cidadão ou servidor responsável pelo registro) informará o identificador do arquivo criado na nuvem constante no JSON recebido na etapa anterior e todas as informações de metadados;
- b - O documento será assinado pelo capturador e posteriormente o documento será enviado para captura, sendo retornado um identificador do evento dessa captura;
- Para todos os outros casos:
- a - O Capturador (o cidadão ou servidor responsável pelo registro) informará o identificador do arquivo criado na nuvem constante no JSON recebido na etapa anterior e todas as informações de metadados;
- b - O documento será enviado para captura, sendo retornado um identificador do evento dessa captura;
- Se for arquivo nato-digital e com Assinatura Eletrônica E-Docs:
- 4 - Captura do documento:
- a - O E-Docs irá colocar o documento na fila de captura, em um objeto de evento, com o identificador recebido na etapa anterior;
- b - Uma vez que o evento seja executado, o objeto de evento será complementado com a informação do identificador do documento capturado;
- 5 - Documento capturado:
- O documento já pode ser utilizado em processos, encaminhamentos, consultas, etc.
Autenticação no E-Docs
A autenticação será através do padrão Bearer Token, utilizando o Access Token obtido através da Autenticação de Usuário no Acesso Cidadão.
- Para as requisições aos endpoints de Fase de Assinatura e Captura será requerido o scope 'api-sigades-documento' no cabeçalho;
- Para as requisições de consulta, será requerido o scope 'api-sigades-consultar' (ou a anterior) no cabeçalho.
Envio de Arquivo para E-Docs
A API do E-Docs aceita apenas arquivos texto, de extensão PDF.
O primeiro endpoint a ser utilizado é o Gerar URL para upload, onde deve ser enviado o tamanho exato do arquivo a ser enviado, recebendo ao final uma url que será utilizada para o envio do arquivo físico.
De posse desse endereço, deve-se realizar uma requisição POST direto para a nuvem do E-Docs, conforme exemplos de código abaixo.
Primeiro criar um modelo que vai conter o JSON recebido no endpoint anterior e o caminho completo do arquivo no servidor local: Agora o método para realizar a requisição POST (essa etapa deve ser realizada imediatamente após a execução da etapa anterior, pois a janela de envio se fecha em poucos segundos)
Observação: Este é um exemplo simplificado, considere as recomendações da Microsoft para utilização de HttpClient. obs: o retorno do post não será um retorno de status 200 com conteúdo como é costumeiro, será apenas um retorno de status 204 No Content (sem conteúdo).
Esse arquivo irá para uma área temporária aguardando os próximos passos de registro dos metadados do Documento. Caso não seja realizado esse próximo passo, esse arquivo será excluído do servidor, por falta de vínculo com um Documento registrado no E-Docs.
Após enviar o documento para a nuvem, o próximo passo é registrar o documento no E-Docs realizando uma Captura.