Gestão Certificado Digital

Informações gerais da Funcionalidade

Nesta página estão centralizadas todas as APIs do Certificado Digital. Vale lembrar que o Certificado é necessário para assinar os documentos que o emissor deseja transmitir a SEFAZ e sem ele não é possível realizar a emissão de documentos fiscais. 

Autenticação

Para acessar as APIs abaixo descritas é necessário autenticar com a chave master, ou seja, a nível de solução. Em caso de dúvidas, confira como autenticar como solução no link Autenticação da Solução

---

Validação de Certificado Digital

Esta API tem por objetivo validar o arquivo que está sendo enviado, garantindo que é válido e não causará rejeição no momento da emissão. 

• API: /certificate/validate?cnpj=
• Método: GET
• Parâmetro envio: CNPJ sem máscara 

Retorno Sucesso (200)

{
 "fimValidade": "2022-09-30T14:32:43.155Z",
 "inativo": false,
 "inicioValidade": "2022-09-30T14:32:43.155Z"
}

---

Possíveis retornos HTTP

• 200 - OK
• 400 - BadRequest
• 401 - Unauthorized
• 404 – NotFound
• 429 - TooManyRequests
• 500 - InternalServerError
• 503 - Service Unavailable

---

Upload de Certificado Digital

Esta API tem por objetivo recepcionar o Certificado Digital do Emissor na Solução Fiscal. 

Por ser um dado sensível e para garantir maior segurança do Certificado Digital trafegado, implementamos uma criptografia hibrida, na qual recebemos o certificado e a senha criptografados em AES, sendo necessário enviar a Chave e Vetor (IV) utilizada na criptografia anterior de forma segura com criptografia RSA.

Para realizar o envio (upload) do Certificado Digital é necessário seguir os seguintes passos:

Passo1. Buscar a chave pública RSA fornecida pela Solução Fiscal através da API /services/getpublickey pelo método GET. Será retornada uma chave RSA com tamanho de 
2048 bits, não sendo necessário enviar informação por parâmetro para obtê-la;

Passo 2. Codificar o conteúdo dos arrays de bytes do certificado e senha do certificado para Base64;

Passo 3. Converter o Certificado e senha do certificado em Base64 para a estrutura de um array de bytes; 

Passo 4. Criptografar os arrays de bytes do Certificado e senha do certificado utilizando algoritmo de criptografia AES. Para isso, utilizar o KeySizeValue/Tamanho da chave: 256; o Mode CBC; o Padding PKCS7; o BlockSizeValue: 128; 

Observação: Normalmente a utilização do algoritmo de criptografia AES cria uma chave (Key) e vetor (IV) automaticamente, porém, deve-se utilizar do mesmo Key e IV para criptografar o certificado e senha do certificado.

Passo 5. Converter para array de bytes a Chave (Key) e Vetor (IV) utilizada na criptografia AES; 

Passo 6. Criptografar a Chave (Key) e Vetor (IV) com a chave pública RSA fornecida anteriormente; 

Passo 7. Converter Chave (Key) e Vetor (IV) criptografados para o formato Base64;

Passo 8. Enviar o Certificado Digital para a API de upload, conforme segue

• API: /certificate/upload
• Método: POST

Body

{
 "cnpj": "String", 
 "senha": " StringBase64", 
 "certificado": " StringBase64",
 "chave": " StringBase64",
 "vetor": " StringBase64",
 "responsavel": "String"
}

---

Response

{
 "EffectiveDate": "datetime",
 "ExpirationDate": "datetime",
 "Message": "string"
}

---

Sendo: 

EffectiveDate: Data contida no certificado referente ao início de validade do certificado.

ExpirationDate: Data contida no certificado referente ao final da validade do certificado.

Caso tenha alguma informação incorreta na requisição, o retorno será HTTP 400.

Possíveis retornos HTTP

• 200 - OK
• 400 - BadRequest
• 401 – Unauthorized
• 429 - TooManyRequests
• 500 - InternalServerError
• 503 - Service Unavailable

---

Download de Certificado Digital

Esta API tem por objetivo disponibilizar o Certificado Digital cadastrado na Solução Fiscal para download. 

Por ser um dado sensível e para garantir maior segurança do Certificado Digital trafegado, implementamos uma criptografia hibrida, na qual  é enviada uma chave pública RSA e depois é criptografado o certificado digital utilizando algoritmo AES. Devolvemos a chave de descriptografia e o vetor de inicialização criptografado em RSA com a chave pública fornecida. 

No envio das informações devem ser seguidas as seguintes regras: 

• Enviar o CNPJ sem máscara;
• A senha do certificado (password) não será enviada na requisição, mas sim em um hash SHA256 gerado sobre a senha do certificado digital;
• Na geração da chave pública RSA (publicKey), seguir a configuração do tamanho de 2048 bits, ser exportada como PKCS1 e enviada no formato Base64.

Para obter o certificado retornado deverá:

• Buscar a chave e vetor retornados, desconverter o Base64 e descriptografar a informação retornada com a chave privada RSA gerada anteriormente. 

• Desconverter o Base64 e descriptografar a informação utilizando algoritmo AES com chave 256, Mode CBC e Padding PKCS7, juntamente com a chave e vetor descriptografado anteriormente para obter o conteúdo do Certificado Digital retornado.

• API: /certificate/download

• Método: POST

Body

{
 "cnpj": "string", 
 "password": " HexString", 
 "publicKey": " StringBase64" 
}

---

Response

{
 "chave": "StringBase64",
 "conteudo": " StringBase64",
 "numeroSerie": "string",
 "vetor": " StringBase64"
}

Possíveis retornos HTTP

• 200 - OK
• 400 - BadRequest
• 401 - Unauthorized
• 404 – NotFound
• 429 - TooManyRequests
• 500 - InternalServerError
• 503 - Service Unavailable