Certificado digital

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.

Tipo A1

Arquivo .pfx ou .p12. Armazenado em software. Suportado pela engineAPI.

Tipo A3

Token físico ou smartcard. Não suportado. Use sempre A1.

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"

import { readFileSync } from 'fs';

const form = new FormData();
form.append('file', new Blob([readFileSync('certificado.pfx')]));
form.append('password', 'senhaDoCertificado');

const resp = await fetch(
  `https://api.engineapi.com.br/v1/companies/${issuerId}/certificate`,
  {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` },
    body: form,
  }
);

if (resp.ok) {
  console.log('Certificado enviado com sucesso');
}

with open('certificado.pfx', 'rb') as f:
    resp = httpx.post(
        f'https://api.engineapi.com.br/v1/companies/{issuer_id}/certificate',
        headers={'Authorization': f'Bearer {token}'},
        files={'file': ('cert.pfx', f, 'application/x-pkcs12')},
        data={'password': 'senhaDoCertificado'},
    )

if resp.status_code == 200:
    print('Certificado enviado com sucesso')

O upload:

Valida a senha

A senha do .pfx é validada antes de gravar. Senha errada retorna erro e nada é persistido.

Extrai a validade real

A data real de validade do certificado é extraída via OpenSSL (certExpiry).

Criptografa e substitui

A senha é criptografada em repouso (certPassword) e o .pfx anterior é removido 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

O upload também extrai o CNPJ do titular do A1 (OID ICP-Brasil 2.16.76.1.3.3, com fallback no CN RAZAO:CNPJ). Esse metadado não volta na resposta pública. Use prontoPara.nfse para saber se o certificado serve para emitir. prontoPara.nfse distingue três recusas de certificado:

`faltando.nfse`	Quando
`certificado`	A1 ausente
`certificadoVencido`	`certExpiry` já passou
`certificadoOutroCnpj`	raiz (8 dígitos) do A1 diferente da do emissor

Filial com e-CNPJ da matriz (mesma pessoa jurídica) não entra em certificadoOutroCnpj: a NFS-e Nacional assina por CNPJ raiz. Nos 30 dias anteriores ao vencimento, avisos[] traz CERTIFICADO_EXPIRANDO (expiresAt, daysUntilExpiry): é aviso, não reprova o cadastro. Se a validade do A1 não pôde ser lida, avisos[] traz CERTIFICADO_VALIDADE_DESCONHECIDA (também aviso; prontoPara.nfse segue true). Até o instante de expirar o emissor continua pronto; se o A1 vencer durante a ida à SEFIN, a recusa é do Fisco.

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. Para o botão de emitir NFS-e, leia prontoPara.nfse: vencido e de outro CNPJ já vêm nomeados em faltando.

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.

Veja também

Primeira emissão: com o certificado pronto, emita sua primeira nota.
Webhooks: configure alertas de validade do certificado.

Comece aqui

Emissão

Tributação

Erros e operação

IA e automação

Conceitos

Migração

Perguntas frequentes

Certificado digital

Tipo A1

Tipo A3

Upload do Certificado

Verificando o Status

Onde Obter um Certificado

Monitorando a Validade

Renovando o Certificado

Veja também

Tipo A1

Tipo A3

​Upload do Certificado

​Verificando o Status

​Onde Obter um Certificado

​Monitorando a Validade

​Renovando o Certificado

​Veja também

Upload do Certificado

Verificando o Status

Onde Obter um Certificado

Monitorando a Validade

Renovando o Certificado

Veja também