# Índice

1. [Quando integrar com certificados digitais?](#quando-integrar)
2. [A integração é segura?](#seguranca)
3. [Integração com a Infosimples](#integracao)
4. [Gerando criptogramas sem código](#gerar-sem-codigo)

## [Quando integrar com certificados digitais?](#quando-integrar)
Algumas APIs disponibilizadas pela Infosimples aceitam certificados digitais PKCS12 (conhecidos popularmente como **Certificados A1**) como parâmetros de entrada. Os certificados são geralmente utilizados pelos sites automatizados para autenticar usuários.

Se você precisa integrar com uma API desse tipo, leia o restante desta página.


## [A integração é segura?](#seguranca)
A integração é significativamente segura. Destacamos os seguintes aspectos:

- A comunicação com a API da Infosimples ocorre exclusivamente via HTTPS (conexão encriptada com TLS), garantindo a integridade dos dados transmitidos (os dados não podem ser modificados durante a comunicação) e que os dados somente podem ser compreendidos pela sua integração e pelo servidor da Infosimples;
- O certificado digital e a sua senha devem ser encriptados (com algoritmo AES, chave de 256 bits e modo GCM) antes de serem transmitidos via HTTPS, adicionando mais uma camada de segurança, autenticação e integridade dos dados;
- O servidor da Infosimples decripta o certificado digital em memória imediatamente antes de usá-lo e, logo depois de ser usado, ele é removido da memória do processo que roda no servidor da Infosimples;
- O certificado digital e a sua senha não são persistidos em estruturas de armazenamento nem em bancos de dados em nenhum momento pela Infosimples, seja em sua forma original ou encriptada;
- As únicas informações associadas ao certificado e à senha persistidas são hashes MD5 do certificado e da sua senha, de forma que seja possível validar que o certificado foi recebido corretamente pelo servidor da Infosimples, sem comprometer a segurança da integração.


## [Integração com a Infosimples](#integracao)
Para desenvolver integrações com as APIs que utilizam certificados digitais A1, é necessário seguir esses passos:

1. Realizar a leitura o arquivo binário do certificado (geralmente é um arquivo com extensão `.pfx`)
2. Converter o arquivo lido para `base64`
3. Encriptar a string `base64` obtida do arquivo de certificado utilizando AES-256, seguindo [as instruções de criptografia](https://api.infosimples.com/consultas/docs/pt-BR/criptografia). A string gerada será usada nos campos com nome `pkcs12_cert`.
4. Encriptar a senha do certificado utilizando AES-256, seguindo [as instruções de criptografia](https://api.infosimples.com/consultas/docs/pt-BR/criptografia). A string gerada será usada nos campos com nome `pkcs12_pass`.

A **chave de criptografia** , utilizada no processo de detalhado acima, é vinculada à sua conta e pode ser encontrada [neste link](https://api.infosimples.com/administracao/conta#chave-criptografia).

A tabela a seguir é um resumo dos campos utilizados nas consultas que usam certificado digital:

| Parâmetro   | Descrição                                                                                                                                                                                           |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pkcs12_cert | Conteúdo do arquivo do certificado digital A1 codificado em Base64 e em seguida encriptado seguindo as [instruções de criptografia](https://api.infosimples.com/consultas/docs/pt-BR/criptografia). |
| pkcs12_pass | Senha do certificado digital encriptado seguindo as [instruções de criptografia](https://api.infosimples.com/consultas/docs/pt-BR/criptografia).                                                    |

Recomendamos que você inicie a sua integração com a API gratuita do link a seguir para validar que o uso de certificados digitais está funcionando corretamente: [Infosimples / Certificado Digital (A1/A3)](https://api.infosimples.com/consultas/docs/pt-BR/infosimples/certificado)

### Exemplos de geração dos criptogramas em diferentes linguagens de programação

> Exemplos baseados no projeto [AesBridge](https://github.com/mervick/aes-bridge).

#### Criptograma utilizado no parâmetro `pkcs12_cert`

#### Python
```python
# Testado com: Python 3.10.19, Python 3.14.0
# pip install aes-bridge
import aes_bridge
import base64

cert_base64 = base64.b64encode(open('caminho/do/arquivo', 'rb').read()).decode()
criptogram = aes_bridge.encrypt(cert_base64, 'INFORME_A_CHAVE_DE_CRIPTOGRAFIA').decode("ascii").replace("+", "-").replace("/", "_").replace("=", "")
```


#### Criptograma utilizado no parâmetro `pkcs12_pass`

#### Python
```python
# Testado com: Python 3.10.19, Python 3.14.0
# pip install aes-bridge
import aes_bridge

criptogram = aes_bridge.encrypt("SENHA_DO_CERTIFICADO", "INFORME_A_CHAVE_DE_CRIPTOGRAFIA",).decode("ascii").replace("+", "-").replace("/", "_").replace("=", "")
```



## [Gerando criptogramas sem código](#gerar-sem-codigo)
Alternativamente, você pode utilizar a ferramenta em https://api.infosimples.com/consultas/docs/pt-BR/certificados.html para gerar os criptogramas manualmente, sem uso de código. Após gerados, você pode copiá-los para os campos `pkcs12_cert` e `pkcs12_pass` da consulta.

Observe que os arquivos e dados informados aqui não são enviados para a Infosimples ou qualquer outro lugar. Os dados são processados apenas dentro do seu browser.


## Precisa de ajuda?
Ainda tem alguma dúvida ou precisa de ajuda na sua integração? Entre em contato em [suporte@infosimples.com.br](mailto:suporte@infosimples.com.br) e receba ajuda da nossa equipe técnica altamente qualificada.