Certificado digital A1
Toda NF-e, NFC-e, CT-e, MDF-e e boa parte das NFS-e saem assinadas com o certificado digital da
empresa. Com estas rotas, o seu sistema instala o certificado A1 (o arquivo .pfx ou .p12)
e acompanha a validade dele, sem ninguém abrir a tela de configuração do FazNota. É útil para
cadastrar empresas em lote e para trocar o certificado antes do vencimento.
Desde a versão 3.20.0.
Endpoints
| Operação | Endpoint |
|---|---|
| Consultar situação e validade do certificado | GET /certificado |
| Instalar (ou trocar) o certificado A1 | POST /certificado/a1 |
As duas rotas respondem na hora: não há recibo nem polling. A autenticação é a mesma de todas as
rotas da v3 (Authorization: Token <chave>). A empresa vem da chave: o certificado é sempre o
da empresa dona da chave, e o corpo não aceita CNPJ nem id de empresa.
-
Converter o arquivo para base64
O
.pfxé binário; a API recebe o conteúdo em base64, no campoarquivo.Terminal window # LinuxARQUIVO=$(base64 -w0 certificado.pfx)# macOSARQUIVO=$(base64 -i certificado.pfx | tr -d '\n')Aceitamos também o formato
data:application/x-pkcs12;base64,...e base64 com quebras de linha. -
Instalar
A senha vem de uma variável de ambiente (não digite na linha de comando: ela fica no histórico do shell). O
jqmonta o JSON, o que resolve senha com aspas ou barra, e ocurllê o corpo da entrada padrão, sem expor arquivo e senha na lista de processos:Terminal window read -rs MYSE_PFX_SENHA && export MYSE_PFX_SENHA # digita sem ecojq -n --arg arquivo "$ARQUIVO" --arg senha "$MYSE_PFX_SENHA" '{arquivo: $arquivo, senha: $senha}' \| curl -X POST $BASE/certificado/a1 \-H "Authorization: Token $TOKEN" \-H "Content-Type: application/json" \--data-binary @-Resposta:
{"status": "001","descricao": "Certificado A1 instalado. As próximas emissões já saem assinadas com ele.","data": {"tipo": "A1","titular": "EMPRESA EXEMPLO LTDA","documento": "12.345.678/0001-99","tipo-documento": "CNPJ","valido-ate": "2027-11-10","dias-para-vencer": 360,"situacao": "VALIDO","dt-vencimento-gravada": "2027-11-10","dt-validade": "2027-11-10"}}Com
001, o certificado já está em uso: a próxima emissão sai assinada com ele. A validade vem emvalido-atee também emdt-validade, a mesma chave da consulta. -
Consultar quando quiser
Terminal window curl $BASE/certificado -H "Authorization: Token $TOKEN"{"status": "005","descricao": "Situação do certificado digital da empresa.","data": {"tipo": "A1","titular": "EMPRESA EXEMPLO LTDA","cnpj": "12345678000199","dt-validade": "2027-11-10","dias-para-vencer": 360,"situacao": "VALIDO","instalado": true}}
Corpo do POST /certificado/a1
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
arquivo | string | Sim | Conteúdo do .pfx/.p12 em base64. Até 50 KB de arquivo (um A1 tem de 3 a 15 KB). |
senha | string | Sim | A senha do arquivo .pfx. Até 128 caracteres. |
Qualquer outro campo é recusado com 400.
O que é conferido antes de gravar
Nada é gravado antes de todas estas travas passarem. São as mesmas regras da tela de upload do FazNota:
- O arquivo abre com a senha e tem chave privada e uso de assinatura digital.
- O certificado é ICP-Brasil (cadeia até a raiz da ICP-Brasil, não autoassinado).
- Está dentro da validade: não venceu e já começou a valer.
- O titular é a empresa da chave: CNPJ com a mesma raiz (matriz e filiais usam o mesmo e-CNPJ) ou, para produtor rural e profissional autônomo, o mesmo CPF do cadastro.
- Não troca um certificado válido por um que vence antes. Se a empresa já tem um certificado
válido até 2027 e você envia um que vence em 2026 (o arquivo antigo, por engano), o atual é
mantido e a resposta é
400explicando as duas datas.
Passando tudo, o FazNota converte o arquivo, grava com segurança, atualiza a data de vencimento (que alimenta os avisos de renovação) e já passa a usar o certificado novo nas emissões.
Situação do certificado
data.situacao no GET /certificado (e no retorno da instalação):
| Situação | Significado |
|---|---|
VALIDO | Instalado e com mais de 30 dias de validade. |
A_VENCER | Instalado, vence em até 30 dias. Hora de renovar com a certificadora. |
VENCIDO | Passou da validade (dias-para-vencer negativo). As emissões são recusadas. |
NAO_INSTALADO | A empresa não tem certificado instalado. |
INDISPONIVEL | Instalado, mas sem data de validade conhecida (caso raro, típico de A3 sem validade registrada). Para um A1, reenvie o arquivo pelo POST /certificado/a1. |
tipo é A1 ou A3. O A3 (token ou cartão) não é instalado pela API: ele fica no computador
da empresa. A consulta informa a validade dele mesmo assim, quando conhecida. titular e cnpj da
consulta são os do cadastro da empresa.
Códigos de status
| Código | Cenário |
|---|---|
005 | GET /certificado: consulta feita. |
001 | POST /certificado/a1: certificado instalado e em uso. |
400 | Campo ausente ou inválido (data.campo: arquivo ou senha), senha errada, arquivo que não é um A1 ICP-Brasil, certificado vencido, de outro CNPJ/CPF ou que vence antes do atual. A descricao diz o motivo. |
999 | Falha interna ao falar com o módulo de certificado, ou limite de instalações por minuto atingido (a descricao diz qual). Tente de novo em instantes. |
Segurança
- A senha, a chave privada e o arquivo nunca aparecem na resposta, nos logs nem nas mensagens de erro do FazNota. O registro de uso da API guarda só que houve uma instalação, sem o conteúdo.
- O certificado só pode ser instalado na empresa da chave, e só se for dela (titular conferido).
- Não há
Idempotency-Keynesta rota: reenviar o mesmo certificado é inofensivo (ele é regravado com a mesma validade).
Boas práticas
- Monitore a validade. Consulte
GET /certificadouma vez por dia e avise o cliente quandosituacaovirarA_VENCER. Um certificado vencido faz todas as emissões serem recusadas. - Troque antes de vencer. Com o certificado novo em mãos, envie pelo
POST /certificado/a1: a troca é imediata e o antigo deixa de ser usado. - Erro de senha? A
descricaodiz quando o arquivo não abre com a senha. Peça a senha de novo ao cliente; o arquivo não é gravado.