Guia: Certificados Digitais
Tudo sobre o certificado digital A1: como obter, fazer upload, monitorar validade e renovar.
Certificados Digitais
Todo documento fiscal eletrônico precisa ser assinado digitalmente com um certificado e-CNPJ. A engineAPI cuida da assinatura automaticamente, você só precisa fazer o upload do arquivo.
Upload do Certificado
POST /v1/companies/{issuerId}/certificate: multipart/form-data, campo do arquivo é
file (não certificate), autenticado por JWT do dashboard.
curl -X POST https://api.engineapi.com.br/v1/companies/ISSUER_ID/certificate \
-H "Authorization: Bearer SEU_TOKEN" \
-F "file=@/caminho/certificado.pfx" \
-F "password=senhaDoCertificado"
O upload:
- Valida a senha do
.pfxantes de gravar (senha errada → erro, nada é persistido). - Extrai a data real de validade do certificado via OpenSSL (
certExpiry). - Criptografa a senha em repouso (
certPassword) e remove o.pfxanterior do disco.
A senha do certificado é criptografada e nunca é retornada pela API após o upload. Você não consegue recuperá-la. Guarde em local seguro.
Verificando o Status
Após o upload, consulte a empresa para conferir o certificado:
curl -X GET https://api.engineapi.com.br/v1/companies/ISSUER_ID \
-H "Authorization: Bearer SEU_TOKEN"
O retorno é o registro do Issuer (com segredos removidos): não existe um objeto
aninhado certificate nem um enum de status (VALID/EXPIRED/etc.). Os campos reais são:
{
"data": {
"id": "ISSUER_ID",
"cnpj": "11222333000181",
"certFilename": "/app/uploads/certificates/9f1c2b3a-....pfx",
"certExpiry": "2027-03-15T00:00:00.000Z"
},
"meta": { "requestId": "req_abc123", "timestamp": "2026-07-06T12:00:00.000Z" }
}
| Campo | Significado |
|---|---|
certFilename | Presente = certificado enviado e validado. null = nenhum certificado ainda |
certExpiry | Data real de expiração (extraída do .pfx via OpenSSL no upload). Compare com new Date() no seu código para decidir se está expirando |
Não confie em um campo de status pronto: calcule os dias restantes a partir de
certExpiry no seu lado, ou use os webhooks certificate.expiring (ver abaixo) que já
fazem esse cálculo no servidor.
Onde Obter um Certificado
Para produção, você precisa de um e-CNPJ A1 emitido por uma Autoridade Certificadora (AC) credenciada pela ICP-Brasil:
| AC | Site |
|---|---|
| Certisign | certisign.com.br |
| Serpro | serpro.gov.br |
| Valid | valid.com |
| Serasa | serasacertificadora.com.br |
| Soluti | soluti.com.br |
Para homologação, você pode usar um certificado de testes emitido por qualquer AC. O SEFAZ de homologação aceita certificados expirados e de teste. Não precisa comprar um certificado só para testar.
Monitorando a Validade
A engineAPI roda uma verificação diária (08h, horário de Brasília) e dispara um único evento de webhook por limiar de dias restantes:
| Evento | Quando | Payload |
|---|---|---|
certificate.expiring | 30, 15, 7, 3 ou 1 dia(s) antes de expirar | { issuerId, issuerName, cnpj, expiresAt, daysUntilExpiry, severity, message } |
Não existem eventos separados expiring_soon/expiring_critical/expired, é sempre o
mesmo certificate.expiring, com daysUntilExpiry e severity indicando a urgência.
Configure seus webhooks em Dashboard → Configurações → Webhooks (ver guia de
webhooks).
Renovando o Certificado
Quando você receber um novo certificado A1 (renovação ou substituição), simplesmente refaça o upload:
curl -X POST https://api.engineapi.com.br/v1/companies/ISSUER_ID/certificate \
-H "Authorization: Bearer SEU_TOKEN" \
-F "file=@novo_certificado.pfx" \
-F "password=novaSenha"
O certificado anterior é substituído automaticamente (o arquivo antigo é removido do disco). Nenhuma emissão em andamento é afetada.